tracing

package
v0.0.0-...-657abb8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 16, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package tracing provides distributed tracing and observability primitives for HELM's AI execution firewall.

It defines a Tracer interface with span lifecycle management and supports multiple export backends (OpenTelemetry, LangSmith, Langfuse). All spans carry a CorrelationID that flows across service boundaries via HTTP headers.

Usage: 

tracer, err := tracing.NewOTelTracer("helm-guardian",
    tracing.WithOTLPEndpoint("localhost:4317"),
    tracing.WithSampleRate(1.0),
)
if err != nil {
    // fall back to noop
    tracer = tracing.NewNoopTracer()
}

ctx, span := tracer.StartSpan(ctx, "policy.evaluate")
defer tracer.EndSpan(span, nil)

Index

Constants

View Source 
const StatusError = "error"

StatusError indicates the span completed with an error.

View Source 
const StatusOK = "ok"

StatusOK indicates the span completed without error.

Variables

This section is empty.

Functions

func InjectHTTPHeaders 

func InjectHTTPHeaders(ctx context.Context, headers http.Header)

InjectHTTPHeaders writes the correlation ID from ctx into headers under the canonical X-Helm-Correlation-ID key. If no ID is present, the header is left unchanged.

func WithCorrelationID 

func WithCorrelationID(ctx context.Context, id CorrelationID) context.Context

WithCorrelationID attaches a correlation ID to ctx and returns the derived context.

Types

type CorrelationID 

type CorrelationID string

CorrelationID is an opaque token used to correlate requests across services.

func ExtractHTTPHeaders 

func ExtractHTTPHeaders(headers http.Header) (CorrelationID, bool)

ExtractHTTPHeaders reads the correlation ID from headers. Returns (id, true) when the header is present and non-empty.

func GetCorrelationID 

func GetCorrelationID(ctx context.Context) (CorrelationID, bool)

GetCorrelationID extracts the correlation ID from ctx. The second return value is false when no ID is present.

func NewCorrelationID 

func NewCorrelationID() CorrelationID

NewCorrelationID generates a new cryptographically random correlation ID.

type Exporter 

type Exporter interface {
	Export(ctx context.Context, spans []Span) error
}

Exporter exports completed spans to an observability backend.

type LangSmithExporter 

type LangSmithExporter struct {
	// contains filtered or unexported fields
}

LangSmithExporter exports HELM spans to LangSmith for LLM observability.

Spans are mapped to LangSmith "runs" using the v1 ingest API. See https://docs.smith.langchain.com/ for API details.

func NewLangSmithExporter 

func NewLangSmithExporter(apiKey, endpoint string) *LangSmithExporter

NewLangSmithExporter creates a new LangSmithExporter. 

e := tracing.NewLangSmithExporter(apiKey, "https://api.smith.langchain.com")

func (*LangSmithExporter) Export 

func (e *LangSmithExporter) Export(ctx context.Context, spans []Span) error

Export serialises spans and POSTs them to the LangSmith runs endpoint.

type LangfuseExporter 

type LangfuseExporter struct {
	// contains filtered or unexported fields
}

LangfuseExporter exports HELM spans to Langfuse for LLM observability.

Spans are mapped to Langfuse "spans" within a trace using the public ingestion API (/api/public/ingestion). Authentication uses HTTP Basic Auth with the public key as the username and the secret key as the password.

func NewLangfuseExporter 

func NewLangfuseExporter(publicKey, secretKey, endpoint string) *LangfuseExporter

NewLangfuseExporter creates a new LangfuseExporter. 

e := tracing.NewLangfuseExporter(publicKey, secretKey, "https://cloud.langfuse.com")

func (*LangfuseExporter) Export 

func (e *LangfuseExporter) Export(ctx context.Context, spans []Span) error

Export serialises spans and POSTs them to the Langfuse ingestion endpoint.

type NoopTracer 

type NoopTracer struct{}

NoopTracer is a Tracer that discards all spans. Use it when tracing is disabled to avoid nil-guard boilerplate.

func (*NoopTracer) EndSpan 

func (n *NoopTracer) EndSpan(span *Span, err error)

EndSpan records the end time and status on the span but does not export it.

func (*NoopTracer) Export 

func (n *NoopTracer) Export(_ context.Context, _ []Span) error

Export is a no-op for the NoopTracer.

func (*NoopTracer) StartSpan 

func (n *NoopTracer) StartSpan(ctx context.Context, name string) (context.Context, *Span)

StartSpan returns a no-op span embedded in the context.

type OTelOption 

type OTelOption func(*otelConfig)

OTelOption is a functional option for NewOTelTracer.

func WithInsecure 

func WithInsecure() OTelOption

WithInsecure disables TLS on the OTLP connection (for local development).

func WithOTLPEndpoint 

func WithOTLPEndpoint(endpoint string) OTelOption

WithOTLPEndpoint sets the OTLP gRPC endpoint for trace export. When omitted, spans are produced but not exported externally.

func WithSampleRate 

func WithSampleRate(rate float64) OTelOption

WithSampleRate sets the fraction of traces to sample (0.0–1.0). Values ≥ 1.0 sample everything; values ≤ 0.0 sample nothing.

type OTelTracer 

type OTelTracer struct {
	// contains filtered or unexported fields
}

OTelTracer implements Tracer backed by the OpenTelemetry SDK. It bridges the HELM Span type to OTel spans so exporters receive both.

func NewOTelTracer 

func NewOTelTracer(serviceName string, opts ...OTelOption) (*OTelTracer, error)

NewOTelTracer creates a Tracer backed by OpenTelemetry. 

tracer, err := tracing.NewOTelTracer("helm-guardian",
    tracing.WithOTLPEndpoint("localhost:4317"),
    tracing.WithSampleRate(1.0),
)

func (*OTelTracer) AddExporter 

func (t *OTelTracer) AddExporter(e Exporter)

AddExporter registers an additional Exporter (e.g. LangSmith, Langfuse). Exporters are called on each EndSpan. Thread-safe.

func (*OTelTracer) EndSpan 

func (t *OTelTracer) EndSpan(span *Span, err error)

EndSpan finalises the HELM span and its underlying OTel span.

func (*OTelTracer) Export 

func (t *OTelTracer) Export(ctx context.Context, spans []Span) error

Export sends spans to all registered Exporters.

func (*OTelTracer) Shutdown 

func (t *OTelTracer) Shutdown(ctx context.Context) error

Shutdown gracefully flushes and stops the underlying OTel provider.

func (*OTelTracer) StartSpan 

func (t *OTelTracer) StartSpan(ctx context.Context, name string) (context.Context, *Span)

StartSpan begins a new HELM span backed by an OTel span.

type Span 

type Span struct {
	TraceID     TraceID           `json:"trace_id"`
	SpanID      SpanID            `json:"span_id"`
	ParentID    SpanID            `json:"parent_id,omitempty"`
	Name        string            `json:"name"`
	StartTimeMs int64             `json:"start_time_ms"`
	EndTimeMs   int64             `json:"end_time_ms,omitempty"`
	Status      string            `json:"status"` // ok, error
	Attributes  map[string]string `json:"attributes,omitempty"`
}

Span represents a unit of work within a trace.

func SpanFromContext 

func SpanFromContext(ctx context.Context) (*Span, bool)

SpanFromContext retrieves the active span from a context, if any.

type SpanID 

type SpanID string

SpanID uniquely identifies a span within a trace.

type TraceID 

type TraceID string

TraceID uniquely identifies a distributed trace.

type Tracer 

type Tracer interface {
	// StartSpan begins a new span under the given context.
	// The returned context carries the span for downstream propagation.
	StartSpan(ctx context.Context, name string) (context.Context, *Span)

	// EndSpan finalises the span. Pass a non-nil err to mark it StatusError.
	EndSpan(span *Span, err error)

	// Export flushes completed spans to the configured backend(s).
	Export(ctx context.Context, spans []Span) error
}

Tracer creates and manages spans for distributed tracing.

func NewNoopTracer 

func NewNoopTracer() Tracer

NewNoopTracer returns a Tracer that performs no operations.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.