telemetry

func WithMetricExemplarFilter ¶

func WithMetricExemplarFilter(filter exemplar.Filter) MetricOption

WithMetricExemplarFilter 配置 exemplar 过滤器，决定哪些测量值会被采样为 exemplar。 exemplar 把一条指标样本与产生它的 trace 关联起来，可在 Grafana 等后端从延迟直方图 直接跳转到对应 trace，便于排查长尾。

SDK 默认即为 exemplar.TraceBasedFilter（仅在当前处于已采样的 trace 上下文时记录）， 因此通常无需显式设置；OTLP exporter 默认会导出 exemplar（Prometheus 需以 OpenMetrics 格式抓取）。可用本选项改为：

• exemplar.AlwaysOnFilter —— 总是记录（无 trace 也记，基数更高）

• exemplar.AlwaysOffFilter —— 完全关闭 exemplar

  WithMetricExemplarFilter(exemplar.AlwaysOffFilter)

也可通过标准环境变量 OTEL_METRICS_EXEMPLAR_FILTER（trace_based / always_on / always_off）配置。

func WithMetricOTLPGRPCReader ¶

func WithMetricOTLPGRPCReader(opts ...otlpmetricgrpc.Option) MetricOption

WithMetricOTLPGRPCReader 通过 OTLP/gRPC（默认端口 4317）周期性上报指标到 Collector。 指标为推送模型，exporter 包在 PeriodicReader 内（默认 60s 间隔）。 不传 opts 时自动读取标准 OTEL_EXPORTER_OTLP_* 环境变量；也可显式配置：

WithMetricOTLPGRPCReader(
	otlpmetricgrpc.WithEndpoint("otel-collector:4317"),
	otlpmetricgrpc.WithInsecure(),
)

需要自定义上报间隔时，改用 WithMetricReader(sdkmetric.NewPeriodicReader(exporter, ...))。

func WithMetricOTLPHTTPReader ¶

func WithMetricOTLPHTTPReader(opts ...otlpmetrichttp.Option) MetricOption

WithMetricOTLPHTTPReader 通过 OTLP/HTTP（默认端口 4318）周期性上报指标。 不传 opts 时自动读取标准 OTEL_EXPORTER_OTLP_* 环境变量；也可显式配置：

WithMetricOTLPHTTPReader(
	otlpmetrichttp.WithEndpoint("otel-collector:4318"),
	otlpmetrichttp.WithInsecure(),
)

func WithMetricOption ¶

func WithMetricOption(opts ...sdkmetric.Option) MetricOption

func WithMetricProvider ¶

func WithMetricProvider(provider metric.MeterProvider) MetricOption

func WithMetricReader ¶

func WithMetricReader(reader sdkmetric.Reader) MetricOption

func WithMetricRuntime ¶

func WithMetricRuntime(opts ...runtime.Option) MetricOption

WithMetricRuntime 启用 Go runtime 指标采集（goroutine 数、GC 次数/暂停、heap 大小等）， 由 OTel contrib 的 runtime instrumentation 提供。默认已开启，调用此方法可传入自定义选项。

// 调整 MemStats 最小读取间隔（默认 15s）
WithMetricRuntime(runtime.WithMinimumReadMemStatsInterval(30 * time.Second))

func WithMetricServiceName ¶

func WithMetricServiceName(serviceName string, extra ...attribute.KeyValue) MetricOption

WithMetricServiceName 为 metric 设置 service.name（外加可选的额外资源属性）。 与 WithTraceServiceName 对应，建议同一服务两处传相同的 serviceName。

func WithMetricStdoutReader ¶

func WithMetricStdoutReader() MetricOption

func WithoutMetricRuntime ¶

func WithoutMetricRuntime() MetricOption

WithoutMetricRuntime 关闭 Go runtime 指标采集。

func WithTraceExporter ¶

func WithTraceExporter(exporter sdktrace.SpanExporter, opts ...sdktrace.BatchSpanProcessorOption) TraceOption

func WithTraceOTLPGRPCExporter ¶

func WithTraceOTLPGRPCExporter(opts ...otlptracegrpc.Option) TraceOption

WithTraceOTLPGRPCExporter 通过 OTLP/gRPC（默认端口 4317）上报 trace 到 Collector （otel-collector / Tempo / Jaeger 等）。不传 opts 时自动读取标准 OTEL_EXPORTER_OTLP_* 环境变量； 也可显式配置：

WithTraceOTLPGRPCExporter(
	otlptracegrpc.WithEndpoint("otel-collector:4317"),
	otlptracegrpc.WithInsecure(), // 无 TLS 的内网 Collector
)

func WithTraceOTLPHTTPExporter ¶

func WithTraceOTLPHTTPExporter(opts ...otlptracehttp.Option) TraceOption

WithTraceOTLPHTTPExporter 通过 OTLP/HTTP（默认端口 4318）上报 trace。 不传 opts 时自动读取标准 OTEL_EXPORTER_OTLP_* 环境变量；也可显式配置：

WithTraceOTLPHTTPExporter(
	otlptracehttp.WithEndpoint("otel-collector:4318"),
	otlptracehttp.WithInsecure(),
)

func WithTracePropagator ¶

func WithTracePropagator(p ...propagation.TextMapPropagator) TraceOption

WithTracePropagator 追加 trace context 传播协议。 默认已启用 W3C TraceContext + Baggage（OTel 推荐组合），调用此方法可追加或替换。

常用示例：

// 追加 B3（兼容 Zipkin/Jaeger 老版本）
import "go.opentelemetry.io/contrib/propagators/b3"
WithTracePropagator(b3.New())

// 只用 B3，不用 W3C（需先调用 WithTracePropagator 再在 Init 里覆盖默认值）
WithTracePropagator(b3.New(b3.WithInjectEncoding(b3.B3SingleHeader)))

func WithTraceProvider ¶

func WithTraceProvider(provider trace.TracerProvider) TraceOption

func WithTraceProviderOption ¶

func WithTraceProviderOption(opts ...sdktrace.TracerProviderOption) TraceOption

func WithTraceSampler ¶

func WithTraceSampler(sampler sdktrace.Sampler) TraceOption

func WithTraceServiceName ¶

func WithTraceServiceName(serviceName string, extra ...attribute.KeyValue) TraceOption

WithTraceServiceName 为 trace 设置 service.name（外加可选的额外资源属性，如版本、环境）。 不设置 Resource 时，Collector 里的 span 缺少 service.name、无法区分来源服务。

WithTraceServiceName("order-api",
	semconv.ServiceVersion("v1.2.0"),
	semconv.DeploymentEnvironmentName("prod"),
)

func WithTraceStdoutExporter ¶

func WithTraceStdoutExporter() TraceOption