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

オープン
#358 コメント 0 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
72/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
技術スタック
go
領域
backend

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.
主要言語
Go
スター
6
フォーク
8
平均マージ
21時間 36分
マージ済み PR(30日)
42

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

OpenNSW/core のほかの issue

OpenNSW/core の issue をすべて見る

似ている issue

Go の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。