What is Super Log?

TypeScript library that emits structured logs following the Superlógica RFCs:

• RFC 0001 (version: 'v1') — legacy envelope with 5 levels and string-array tags
• RFC 0002 (version: 'v2', default) — application + audit envelopes, snake_case field emission, JSON-string serialization for tags/roles/details, and a 1024-byte total cap

Install

npm install @superlogica/super-log-js

RFC 0002 (default)

import { SuperLogAdapter } from '@superlogica/super-log-js'

const log = new SuperLogAdapter({
  application: 'paybox',
  environment: 'prd' // 'prd' | 'hml' | 'dev'
})

log.info({
  traceId: '7bba9f33312b3dbb8b2c2c62bb7abe2d',
  spanId: '086e83747d0e381e',
  message: 'Request received',
  tags: { licenca: 'adm01', tenant_id: 'tenant_001' }
})

Emitted line (single-line JSON, ≤ 1024 bytes):

{"level":"info","timestamp":"2026-02-13T14:30:45.123Z","type":"application","message":"Request received","span_id":"086e83747d0e381e","trace_id":"7bba9f33312b3dbb8b2c2c62bb7abe2d","application":"paybox","environment":"prd","version":"v2","tags":"{\"licenca\":\"adm01\",\"tenant_id\":\"tenant_001\"}"}

Audit logs

log.audit.info({
  message: 'Alteração de permissão de usuário',
  category: 'security',
  eventType: 'permission_change',
  result: 'success',
  userId: 'admin_001',
  userEmail: '[email protected]',
  affectedUserId: 'user_12345',
  roles: ['admin'],
  details: { previous_value: 'admin', new_value: 'user', reason: 'privilege downgrade' }
})

type is set to "audit" automatically. tags, roles, and object-form details are JSON-serialized to escaped strings per RFC 0002.

Emitted line:

{"level":"info","timestamp":"2026-02-20T15:42:31.847Z","type":"audit","message":"Alteração de permissão de usuário","application":"paybox","environment":"prd","version":"v2","category":"security","event_type":"permission_change","result":"success","user_id":"admin_001","user_email":"[email protected]","affected_user_id":"user_12345","roles":"[\"admin\"]","details":"{\"previous_value\":\"admin\",\"new_value\":\"user\",\"reason\":\"privilege downgrade\"}"}

Limits enforced (RFC 0002)

| Field | Limit | Behavior | |--------------|--------------|--------------------------------------------| | message | 512 bytes | truncated, with a trailing ... indicator | | application| 32 bytes | truncated at constructor | | tags | 256 bytes, 3 | entries beyond the 3rd dropped; trailing entries removed to fit 256 B | | details | 512 bytes | truncated (... when given as free-text string; hard-cut when object) | | audit IDs | 128–256 B | truncated per field | | total log | 1024 bytes | message → details → tags truncation order |

When a free-text field overflows, the truncated value ends with ... (3 bytes, reserved within the limit) so consumers can tell the content was cut. Identifiers and serialized objects are hard-cut without the indicator. Truncation never splits a multi-byte character or emoji.

Disabling limits (enforceLimits)

Both versions accept an optional enforceLimits flag (default true). Set it to false to log everything in full — no truncation, no ... indicator, no tag cap, and no total-log budget:

const log = new SuperLogAdapter({
  application: 'paybox',
  environment: 'prd',
  enforceLimits: false // log everything untruncated
})

Environment validation

environment must be one of the RFC-defined values. Invalid values throw at construction.

Trace context listeners

log.addTraceContextListener({ getTraceContext: () => ({ traceId, spanId }) })

When traceId/spanId is omitted from the input, the adapter polls listeners in insertion order and uses the first non-empty context.

RFC 0001 (v1)

import { SuperLogAdapter } from '@superlogica/super-log-js'

const log = new SuperLogAdapter({
  version: 'v1',
  application: 'condominios',
  environment: 'prod', // 'dev' | 'prod' | 'stage' | 'sandbox'
  channel: 'default' // optional, defaults to 'default'
})

log.warning({
  message: 'Arrecadação com tempo maior do que o habitual',
  tags: ['arrecadacao', 'performance']
})

Emitted line:

{"level":"warning","timestamp":"2021-10-03T12:00:00Z","message":"Arrecadação com tempo maior do que o habitual","channel":"default","application":"condominios","environment":"prod","tags":["arrecadacao","performance"]}

v1 levels: warning | critical | fatal | debug | info. v1 has no trace/span fields, no audit namespace, and no type field.

The v1 message field is capped at 1024 bytes (truncated with a trailing ... indicator). v1 does not cap the number of tags — the 3-item tag cap applies to v2 only. Pass enforceLimits: false to log the full message untruncated:

new SuperLogAdapter({
  version: 'v1',
  application: 'condominios',
  environment: 'prod',
  enforceLimits: false
})

Redaction

Both versions accept a pino-style redact config:

new SuperLogAdapter({
  application: 'app',
  environment: 'dev',
  redact: { paths: ['message.password', 'message.creditCard'], censor: '***' }
})

Note for v2: tags, roles, and details are emitted as already-serialized strings, so redact paths cannot reach keys inside them after serialization — redact at the input level when the field is still an object.

Pretty printing

Pass isPretty: true in either version to enable human-readable output via pino-pretty (useful in development).

const log = new SuperLogAdapter({
  application: 'app',
  environment: 'dev',
  isPretty: true
})

Migration: 2.x → 3.x

• tags, roles, and details are now emitted as JSON-escaped strings. Parsers must JSON.parse these fields.
• A new type field is emitted (application or audit).
• environment is validated — use the values prescribed by the RFC version you instantiate.
• Legacy generic type exports (Log, LogInput, Alert, Critical, Debug, Error, Info, Warning, Channel, Level, Tags) were removed. Import their versioned counterparts: LogV2 / LogV1, LogInputV2 / LogInputV1, TagsV2 / TagsV1, LevelV2 / LevelV1, ChannelV1.
• v1 consumers must now pass version: 'v1' explicitly and may use channel; traceId / spanId are not accepted in v1.

Authors

Do you have any questions about the project? Contact the authors:

• Matheus Pereira Leal ([email protected])