Documentation
¶
Overview ¶
Package tracing provides OpenTelemetry distributed tracing for cloop.
When tracing is enabled (config.Tracing.Enabled = true and Endpoint is set), the package initialises a global OTel TracerProvider that exports spans via OTLP over HTTP to the configured endpoint (e.g. a local Jaeger or OTEL Collector). When disabled, a no-op tracer is used so callers never need to guard on nil spans.
Span hierarchy produced during a PM run:
plan_run (one per cloop run)
└─ task_execute (one per task)
└─ provider_call (one per Complete() invocation)
Index ¶
- func SpanIDFromContext(ctx context.Context) string
- func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
- func TraceIDFromContext(ctx context.Context) string
- func WrapProvider(inner provider.Provider) provider.Provider
- type Config
- type ShutdownFunc
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SpanIDFromContext ¶
SpanIDFromContext returns the hex-encoded span ID of the current span in ctx, or empty when no valid span is active.
func StartSpan ¶
func StartSpan(ctx context.Context, name string, attrs ...attribute.KeyValue) (context.Context, trace.Span)
StartSpan starts a new span named name as a child of the span already in ctx (if any). Extra span attributes can be provided via attrs. The returned context carries the new span; callers must call span.End().
func TraceIDFromContext ¶
TraceIDFromContext returns the hex-encoded trace ID of the current span in ctx, or an empty string when no active span is present (tracing disabled or no span started).
func WrapProvider ¶
WrapProvider returns a provider.Provider that wraps inner and records one "provider_call" OTel span per Complete() invocation. The span captures:
- provider name and model as attributes
- input/output token counts after completion
- wall-clock duration (via span start/end)
- error status if the call fails
When tracing is disabled (no-op tracer), the wrapper is zero-overhead.
Types ¶
type Config ¶
type Config struct {
// Enabled activates OTLP trace export. Default: false.
Enabled bool `yaml:"enabled,omitempty"`
// Endpoint is the OTLP HTTP receiver URL, e.g. "http://localhost:4318".
// The exporter uses the /v1/traces path automatically.
// Required when Enabled is true; ignored otherwise.
Endpoint string `yaml:"endpoint,omitempty"`
// ServiceName is reported as the OTel service.name resource attribute.
// Defaults to "cloop".
ServiceName string `yaml:"service_name,omitempty"`
}
Config holds tracing settings loaded from .cloop/config.yaml under the "tracing" key. All fields are optional; when Enabled is false (default) the no-op tracer is used and no network connections are made.
type ShutdownFunc ¶
ShutdownFunc flushes and closes the TracerProvider. Always safe to call, even when tracing is disabled (it becomes a no-op).
func Init ¶
func Init(cfg Config) (ShutdownFunc, error)
Init configures the global OTel TracerProvider using the given Config. When cfg.Enabled is false or cfg.Endpoint is empty, a no-op tracer is installed and shutdown is a harmless no-op. The caller must invoke the returned ShutdownFunc (e.g. via defer) to flush pending spans before exit.
Source Files