Logs & parsers

A service's logs are shown live in its panel. You can filter them by level or text. You can also clear the view or export it.

In addition to the process's stdout/stderr, a service can read logs from a file, a MongoDB database or a MySQL database: see Log sources.

Levels

The level is inferred from the line's text:

Level	Matched on
fatal	fatal, FATAL
error	error, ERROR, ERR
warn	warn, WARN, WARNING
debug	debug, DEBUG, DBG
info	info, INFO, INF

With no match, a stderr line is error, a stdout line info.

Parsers

A parser is a JavaScript function that takes a line and returns another. Several parsers run one after the other in the order you set. Each one receives the output of the previous one.

interface LogLine {
  raw: string       // the original text, not changeable
  stream: string    // 'stdout' | 'stderr', not changeable
  level: string     // the level, changeable
  message: string   // what is displayed, changeable
  hidden: boolean   // set true to hide the line
  metadata: object  // whatever you want to attach
  json?: object     // present when the built-in JSON parser (native:json) ran before
}

Return the line untouched when your parser does not apply.

Reading structured JSON

For winston, pino, or any JSON logging:

(line) => {
  if (!line.json) return line
  return {
    ...line,
    level: line.json.level ?? line.level,
    message: line.json.msg ?? line.json.message ?? line.raw,
    metadata: { service: line.json.service, trace: line.json.trace },
  }
}

Hiding noise

(line) => line.raw.includes('GET /health') ? { ...line, hidden: true } : line

What a parser can and cannot do

It runs in isolation and can only use RegExp, String, Object, Array, JSON, Math and Date. It has no require, no file access and no network access. It gets 50 ms per line. A line that takes longer passes unchanged. After 10 consecutive timeouts, the parser is disabled. If it throws an error, the line is passed unchanged to the next parser.

On output, the message is truncated at 16 KB and metadata at 100 keys.

Attaching a parser

Parsers are defined in Settings → Log Parsers, and attached to a service from its Log parsers tab, in the execution order you want.

A shared parser runs on your teammates' machines

A parser belongs to the organization of the open project and is synced to its members. This lets them read the logs of a shared service. With no cloud project open, a parser stays on your machine.

If you edit a parser, you change the code that runs on your team's machines. The settings screen says who owns each parser.