Structured Logging Best Practices for Node.js, Python and Go
OpenTelemetry Logs just went stable in Go and JavaScript. Here is how to write logs that machines can query and humans can follow, from one request in the browser to the line that explains why it failed.
Dmytro Vavreniuk
Product Engineer
Short version: structured logging means one JSON object per line with consistent field names. Keep messages constant and put variables in fields, use OpenTelemetry names for the fields every service shares (service.name, trace_id, span_id, session.id), redact secrets in the logger itself, and write to stdout. Use pino in Node.js, structlog in Python and log/slog in Go. With OpenTelemetry Logs now stable in Go and JavaScript, connecting every log line to its trace and its user session is a configuration step, not a project.
Two releases this autumn changed the default advice on structured logging. On October 2, 2026, OpenTelemetry Go v1.47.0 shipped the first stable release of its Logs API and SDK, after a release candidate in August. On November 5, 2026, the project announced the JavaScript SDK 3.0, which folds the logs API into @opentelemetry/api and makes traces, metrics and logs all stable in JavaScript. Python's logs SDK still lives under an underscored, experimental module path, though it is widely used in production.
What this means in practice: the plumbing that links a log line to a trace is no longer the hard part. The hard part is still the logs themselves. A stable OTLP pipeline that carries "something went wrong" with no fields is a very reliable way to store useless text. This guide is our hub for logging and observability: the practices first, then working setups for Node.js, Python and Go, then how to ship logs and connect them to what the user actually saw.
What structured logging is, in one example
A structured log entry is a record of named fields instead of a sentence. Compare the two lines below. Both describe the same event, but only the second one lets you ask "how many card_declined errors did checkout-api log in the last hour, and for which sessions?" without writing a regular expression.
# Unstructured: easy to write, painful to query
2026-11-17 09:14:02 ERROR Payment failed for user 4821 order 99173 (card_declined) after 2 retries
# Structured: one JSON object per line, one meaning per field
{"time":"2026-11-17T09:14:02.481Z","level":"error","msg":"payment failed",
"service.name":"checkout-api","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736",
"span_id":"00f067aa0ba902b7","session.id":"s_7f3c2a","user_id":"u_4821",
"order_id":"99173","error.type":"card_declined","retry_count":2}The rule behind it: the message says what happened, the fields say to whom, where and how much. The message stays the same every time the event happens, so you can count it. Everything that changes goes into a field with a predictable name and type.
Best practice 1: agree on field names before you write code
The biggest structured logging failure is not unstructured logs, it is ten services with ten names for the same thing: userId, user_id, uid, user.id. Queries and dashboards then only work for the service whose author wrote them. Write a short field dictionary and put it in your repo.
For the fields every service shares, borrow names from the OpenTelemetry semantic conventions rather than inventing your own. Your traces and metrics will use them anyway, and backends know how to map them. For business fields (order_id, plan), plain snake_case is fine. A practical starting set:
| Field | Example | Why |
|---|---|---|
time | 2026-11-17T09:14:02.481Z | UTC, ISO 8601 / RFC 3339 with at least milliseconds. Never local time. Go slog and pino already use this key. |
level | error | Text from a small fixed set (debug, info, warn, error). slog writes INFO, pino info: pick one case or normalize in the collector. |
msg | payment failed | A stable, constant phrase. Variables go into fields, so you can count by message. |
service.name | checkout-api | OpenTelemetry resource attribute; same name your traces and metrics use. |
deployment.environment | production | Lets one backend hold staging and prod without guessing. |
trace_id / span_id | 4bf92f35... / 00f067aa... | Links the line to a distributed trace. Hex strings, W3C Trace Context format. |
session.id | s_7f3c2a | OpenTelemetry semantic convention for a user session; links backend logs to the session replay. |
user_id | u_4821 | An internal, pseudonymous ID. Never an email address or name. |
error.type | card_declined | A low-cardinality error class you can group and alert on. |
duration_ms | 412 | Units in the field name. A number, not the string "412ms". |
Keep types stable too. If order_id is a string in one service and a number in another, some backends will map the field to whichever type they saw first and silently drop the rest.
Best practice 2: make levels mean something
Levels are only useful if the team agrees what they mean. A definition that works for most services:
- error: a request or job failed and someone should look at it. If nobody would ever act on it, it is not an error.
- warn: something unexpected happened but the system recovered (a retry succeeded, a fallback was used). Worth counting, not worth waking anyone.
- info: business events and lifecycle events: order placed, user signed up, service started, config loaded. Your production default.
- debug: detail for developers. Off in production, but switchable at runtime per service (an environment variable or an admin endpoint) so you can turn it on during an incident without a deploy.
Log an error once, where it is handled, not at every layer it passes through. Five copies of the same stack trace make incidents look five times bigger than they are and cost five times as much to store.
Best practice 3: carry context, do not repeat it
Request-level fields (session, route, user, trace) should be attached once at the start of a request and then appear on every line automatically. Every mainstream library has a mechanism for it: child loggers in pino, context variables in structlog, logger.With plus context.Context in Go. If developers have to pass user_id by hand to each log call, half of the calls will forget it.
The two context fields that pay off most are trace_id, which links the line to every other service the request touched, and session.id, which links it to the user's browser session. With both, an error log becomes a starting point: open the trace to see which downstream call failed, open the session replay to see what the user clicked before it happened.
Best practice 4: redact at the source
Logs are copied everywhere: disks, collectors, third-party backends, laptops during an incident. Anything sensitive that reaches a log line should be treated as leaked. Redact in the logger configuration, not in a downstream pipeline that someone may bypass:
- Never log passwords, tokens, API keys, session cookies,
Authorizationheaders or payment data. - Log internal pseudonymous IDs instead of names and email addresses. Under GDPR they are still personal data, so set a retention period for logs, as you would for session recordings.
- Do not log whole request or response bodies by default. Log the few fields you need.
- Use the library's redaction feature (pino
redact, a structlog processor, a Goslog.LogValuertype) so the rule is enforced by code.
Node.js: pino plus OpenTelemetry
pino writes newline-delimited JSON by default and is among the fastest Node.js loggers because it does as little work as possible on the main thread. This setup gives ISO timestamps, text levels, built-in redaction and a child logger per request:
// logger.js - pino 9/10, JSON to stdout
import pino from 'pino';
export const logger = pino({
level: process.env.LOG_LEVEL ?? 'info',
base: { 'service.name': 'checkout-api', 'deployment.environment': process.env.APP_ENV },
timestamp: pino.stdTimeFunctions.isoTime, // "time":"2026-11-17T09:14:02.481Z" (same key as slog)
formatters: { level: (label) => ({ level: label }) }, // "level":"error" instead of 50
redact: {
paths: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.card_number'],
censor: '[REDACTED]',
},
});
// Express middleware: one child logger per request carries the shared context
export function requestLogger(req, res, next) {
req.log = logger.child({
'session.id': req.get('x-session-id'), // set by the browser, see below
'http.request.method': req.method,
'http.route': req.route?.path ?? req.path,
});
next();
}
// In a route: a stable message plus fields, never values glued into the message
req.log.info({ order_id: order.id, total_cents: order.totalCents }, 'order placed');
req.log.error({ err, order_id: order.id, retry_count: 2 }, 'payment failed');Note the error call: pass the error object as err and pino's standard serializer writes its type, message and stack as fields of the same JSON line. Use pino-pretty only on your laptop, never in production.
For trace correlation, the OpenTelemetry pino instrumentation injects trace_id, span_id and trace_flags into each record when a span is active, and can also forward the records to the OpenTelemetry Logs SDK. The easiest way to get it is zero-code instrumentation. The JS SDK 3.0 announcement says users of auto-instrumentations-node in zero-code mode do not need to change anything for the upgrade; it does raise the minimum Node.js version to 22.15.
# Zero-code OpenTelemetry for Node.js (Node >= 22.15 for JS SDK 3.x)
npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
export OTEL_SERVICE_NAME=checkout-api
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp # also ship pino records as OTel logs
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
node --require @opentelemetry/auto-instrumentations-node/register app.js
# pino lines now also carry trace_id, span_id and trace_flags when a span is activePython: structlog with context variables
structlog builds each log entry as a dictionary and passes it through a chain of processors, which makes structure, redaction and correlation easy to add in one place. Its contextvars integration works with asyncio, so request fields bound in a FastAPI middleware appear on every line logged while that request is handled.
# logging_setup.py - structlog with JSON output and trace correlation
import logging
import structlog
from opentelemetry import trace
def add_trace_ids(logger, method_name, event_dict):
ctx = trace.get_current_span().get_span_context()
if ctx.is_valid:
event_dict["trace_id"] = format(ctx.trace_id, "032x")
event_dict["span_id"] = format(ctx.span_id, "016x")
return event_dict
def drop_secrets(logger, method_name, event_dict):
for key in ("password", "token", "authorization", "card_number"):
if key in event_dict:
event_dict[key] = "[REDACTED]"
return event_dict
structlog.configure(
processors=[
structlog.contextvars.merge_contextvars, # request-scoped fields
structlog.processors.add_log_level,
structlog.processors.TimeStamper(fmt="iso", utc=True, key="time"),
add_trace_ids,
drop_secrets,
structlog.processors.dict_tracebacks, # exceptions as JSON, not text
structlog.processors.EventRenamer("msg"),
structlog.processors.JSONRenderer(),
],
wrapper_class=structlog.make_filtering_bound_logger(logging.INFO),
)
log = structlog.get_logger()
# FastAPI / Starlette middleware: bind once per request
structlog.contextvars.clear_contextvars()
structlog.contextvars.bind_contextvars(**{
"service.name": "checkout-api",
"session.id": request.headers.get("x-session-id"),
"http.route": "/checkout",
})
log.info("order placed", order_id=order.id, total_cents=order.total_cents)If you prefer the standard logging module, a JSON formatter plus OpenTelemetry's LoggingInstrumentor (from opentelemetry-instrumentation-logging) adds trace and span IDs to each record. To send records to an OTLP endpoint, OpenTelemetry Python provides a LoggingHandler; it still sits under the experimental opentelemetry.sdk._logs path, so pin your versions.
Go: log/slog and the now-stable OpenTelemetry Logs
Since Go 1.21 the standard library has a structured logger, log/slog, and for most services it replaces zap and zerolog. The snippet below writes JSON to stdout, adds trace IDs from the request context, and shows the LogValuer trick that makes a secret type impossible to print:
// logging.go - Go log/slog, JSON to stdout, trace IDs from context
package logging
import (
"context"
"log/slog"
"os"
"go.opentelemetry.io/otel/trace"
)
// traceHandler adds trace_id and span_id from the context to every record.
type traceHandler struct{ slog.Handler }
func (h traceHandler) Handle(ctx context.Context, r slog.Record) error {
if sc := trace.SpanContextFromContext(ctx); sc.IsValid() {
r.AddAttrs(
slog.String("trace_id", sc.TraceID().String()),
slog.String("span_id", sc.SpanID().String()),
)
}
return h.Handler.Handle(ctx, r)
}
// Keep the wrapper when callers use logger.With(...) or WithGroup(...).
func (h traceHandler) WithAttrs(as []slog.Attr) slog.Handler { return traceHandler{h.Handler.WithAttrs(as)} }
func (h traceHandler) WithGroup(n string) slog.Handler { return traceHandler{h.Handler.WithGroup(n)} }
// Secret never prints its value, wherever it is logged.
type Secret string
func (Secret) LogValue() slog.Value { return slog.StringValue("[REDACTED]") }
func New() *slog.Logger {
base := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
return slog.New(traceHandler{base}).With(slog.String("service.name", "checkout-api"))
}
// In an HTTP handler: always use the ...Context methods so the trace is found.
// log := logger.With(slog.String("session.id", r.Header.Get("X-Session-Id")))
// log.InfoContext(r.Context(), "order placed",
// slog.String("order_id", id), slog.Int("total_cents", total))The detail that trips people up: trace IDs live in context.Context, so you must call InfoContext, ErrorContext and friends, not Info. A linter rule (for example sloglint with its context option) catches the plain calls in review.
If you would rather send logs over OTLP than parse stdout, the contrib bridge go.opentelemetry.io/contrib/bridges/otelslog implements slog.Handler on top of the OpenTelemetry Logs API, which is now covered by v1 compatibility guarantees. One change to know when upgrading to v1.47: the global logger provider functions moved to the root go.opentelemetry.io/otel package (otel.SetLoggerProvider, otel.GetLoggerProvider), and the old ones in otel/log/global are deprecated.
Shipping logs: stdout and a collector, OTLP, or both
There are two sound ways to get structured logs out of an application:
- stdout plus a collector. The app writes JSON lines; the OpenTelemetry Collector, Fluent Bit or Vector tails the container log files and ships them. Logs survive an app crash,
kubectl logskeeps working, and the app has no network dependency for logging. The cost is a parsing step. - OTLP from the app. A logging bridge sends records with typed attributes and trace context directly to an OTLP endpoint. No parsing, richer data, and now stable in Go and JavaScript. The cost is that a crash can lose the last buffered batch, and the app depends on the collector being reachable.
In Kubernetes we recommend stdout as the source of truth and a collector that parses the JSON and keeps the correlation fields. A minimal OpenTelemetry Collector receiver for that:
# OpenTelemetry Collector: read JSON container logs and keep the fields
receivers:
filelog:
include: [/var/log/pods/*/*/*.log]
operators:
- type: container # unwrap the CRI/Docker line format
- type: json_parser
parse_from: body
timestamp: { parse_from: attributes.time, layout_type: gotime, layout: "2006-01-02T15:04:05.999999999Z07:00" }
severity: { parse_from: attributes.level }
- type: trace_parser # promote trace_id/span_id to the record
trace_id: { parse_from: attributes.trace_id }
span_id: { parse_from: attributes.span_id }Which logs are worth collecting at all, and which to drop before they cost money, is covered in Kubernetes logging: what to collect and ignore. The short rule: sample or drop health checks and successful high-volume debug paths at the collector, and never sample errors.
From backend log to what the user saw: session.id end to end
A trace ID tells you what happened inside your systems. It does not tell you what the user did before the failing request: the double click, the back button, the form field they left empty. That lives in the browser, which is why session replay and logs work best together.
The link is one shared identifier. OpenTelemetry defines session.id in its semantic conventions, and in 2026 replay tools started using it: ClickStack, for example, began reading the OpenTelemetry session.id for its replay views in October (we covered that in open-source vs SaaS session replay tools). Send the replay's session ID with each API call and log it on the backend:
// Browser: send the replay session ID with every API call
const sessionId = getReplaySessionId(); // the same ID your session replay tool uses
const originalFetch = window.fetch;
window.fetch = (input, init = {}) => {
const headers = new Headers(init.headers);
headers.set('x-session-id', sessionId);
return originalFetch(input, { ...init, headers });
};
// Or use W3C baggage ("baggage: session.id=...") if you already run
// OpenTelemetry in the browser, so it travels through every service.Now an error line with session.id is a direct link to the recording, and a confusing recording is a direct query into the backend logs for the same session. That workflow, from error to replay and back, is what we walk through in error tracking with session replay and network debugging with session replay. If you are new to replay itself, start with what is session replay.
Structured logging checklist
Run through this list for each service. Each line has a quick test you can do today:
| Practice | Quick test |
|---|---|
| One JSON object per line on stdout | Pipe a log line into jq: does it parse? |
| Constant messages, variables in fields | Group by msg in your log tool: are there tens of distinct values, not thousands? |
| Shared field names across services | Is it service.name everywhere, or also app, svc, service? |
| Levels mean something | Does every error line deserve a human looking at it? |
| trace_id and session.id on request logs | Can you go from one log line to the trace and the user session in one click? |
| Secrets and personal data redacted at the source | grep your logs for "Bearer", "@" and "password" |
| Exceptions as structured fields | Is the stack trace inside the JSON line, not 40 separate lines? |
| Volume under control | Do you know your top 10 messages by count and what they cost per month? |
Frequently asked questions
What is structured logging?
Structured logging means writing each log entry as a set of named fields, usually one JSON object per line, instead of a free-text sentence. A log tool can then filter, group and count by any field (service, user, order, trace ID) without fragile regular expressions.
What is the best structured logging library for Node.js, Python and Go?
For Node.js, pino is the usual choice because it is fast and JSON-first; winston also works. For Python, structlog gives the cleanest API, and the standard logging module with a JSON formatter is fine if you cannot add dependencies. For Go, use the standard library log/slog (Go 1.21+); zap and zerolog are still good, but slog removes the need for a third-party package in most services.
Should logs go to stdout or directly to an OpenTelemetry endpoint?
In containers, write JSON to stdout and let a collector (OpenTelemetry Collector, Fluent Bit, Vector) ship it. Logs survive application crashes and kubectl logs keeps working. Sending logs over OTLP directly from the app through a logging bridge avoids parsing and is now well supported in Go and JavaScript, where OpenTelemetry Logs became stable in October and November 2026. Many teams do both: stdout for safety, OTLP for rich attributes.
How do I correlate logs with traces?
Add the active trace_id and span_id to every log record made during a request. OpenTelemetry logging bridges and instrumentations (pino instrumentation in Node.js, LoggingInstrumentor in Python, the otelslog bridge or a small slog handler in Go) do this for you when a span is active. Your log backend can then jump from a log line to the full trace.
Is it safe to log user IDs under GDPR?
A pseudonymous internal ID is still personal data under GDPR, but logging it for debugging and security is usually justifiable when you limit retention and access. Do not log names, email addresses, full IP addresses, tokens or payment data. Redact at the source, in the logger configuration, so sensitive values never reach disk or a third-party service.
Further reading
- Kubernetes logging: what to collect and ignore
- Error tracking with session replay for production debugging
- Open-source vs SaaS session replay tools in 2027
- LogNroll product overview
See the user session behind every error and log line. Try LogNroll for free.