trace/logging: write trace_id and span_id as OpenTelemetry names them

Open
#358 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
72/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
go
Domain
backend

Research direction

Start by reading the trace/logging.Handler implementation and its existing tests; the issue does not name specific file paths. Check how it currently adds traceId, then inspect the available trace context APIs in the Go OpenTelemetry trace package. Done means logs use trace_id, include span_id for a valid active span, and retain the correlation ID fallback when no valid span exists.

Written by the indexing model from the issue text.

Description

Type/Improvement
Current Limitation

trace/logging.Handler adds the request's correlation ID to log lines, but the output doesn't follow the OpenTelemetry convention for trace context in logs, and it can't add a span ID:

  • Field name. It writes traceId. The OTel spec for non-OTLP log formats (Trace Context in non-OTLP Log Formats) names the fields trace_id, span_id and trace_flags. Collectors and backends (the Collector's filelog receiver, Loki/Grafana derived fields, OpenObserve) pick up those names when linking logs to traces. With traceId, every consumer needs its own parsing rule.
  • No span ID. The handler reads only trace.GetTraceID(ctx). When the context carries an active OTel span, its span ID never reaches the log line, so a line can be linked to a trace but not to the span (the hop or operation) that wrote it.
  • Can disagree with the span's trace ID. The value comes from TraceMiddleware, not from the OTel span. Unless a service adds something like the custom IDGenerator in OpenNSW/nsw-srilanka#866, the traceId in the logs and the trace ID of the spans are different values for the same request.
Suggested Improvement

Make trace/logging.Handler write trace context as the OTel convention describes:

  1. Rename the field from traceId to trace_id.
  2. Prefer the active OTel span. If oteltrace.SpanContextFromContext(ctx).IsValid(), add:
    • trace_id: sc.TraceID().String() (32 lowercase hex characters)
    • span_id: sc.SpanID().String() (16 lowercase hex characters)
    • optionally trace_flags: sc.TraceFlags() as 2 hex characters
  3. Fall back to trace.GetTraceID(ctx) as trace_id when there's no valid span, as today.
func (h *Handler) Handle(ctx context.Context, record slog.Record) error {
	if sc := oteltrace.SpanContextFromContext(ctx); sc.IsValid() {
		record.AddAttrs(
			slog.String("trace_id", sc.TraceID().String()),
			slog.String("span_id", sc.SpanID().String()),
		)
	} else if traceID := trace.GetTraceID(ctx); traceID != "" {
		record.AddAttrs(slog.String("trace_id", traceID))
	}
	return h.Handler.Handle(ctx, record)
}
  • Services without OTel tracing keep working unchanged, apart from the field name.
  • This adds a dependency on go.opentelemetry.io/otel/trace (API only, no SDK) to the trace module.
  • Renaming the field is a breaking change for anything that queries traceId in logs. Release it as a new minor version and note it in the release notes.

Out of scope: the traceId / correlationId names in httputil error responses, and where TraceMiddleware gets its ID from (#349).

Version

github.com/OpenNSW/core/trace v0.2.0

Additional Context
  • Needed by openndx/openndx-core#702 (adopt core/trace, trace_id on log lines) and openndx/openndx-core#711 (OTel tracing, span_id on log lines). openndx-core's logging standard (openndx/openndx-core#708) specifies trace_id.
  • Related to #349: once TraceMiddleware takes its ID from the active span, step 3's fallback only applies to services without OTel tracing, and logs and spans always share one trace ID.
Dominant language
Go
Stars
6
Forks
8
Avg merge
21h 36m
Merged PRs (30d)
42

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from OpenNSW/core

All issues in OpenNSW/core

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.