Documentation
¶
Overview ¶
Package telemetry provides OpenTelemetry instrumentation for AILANG.
This package enables OTLP export of traces, metrics, and logs to any OpenTelemetry-compatible backend (ai-observer, Grafana, Honeycomb, etc.).
Configuration ¶
Telemetry is opt-in and configured via standard OpenTelemetry environment variables:
OTEL_SERVICE_NAME=ailang-coordinator OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf OTEL_TRACES_EXPORTER=otlp OTEL_METRICS_EXPORTER=otlp
Usage ¶
ctx := context.Background()
shutdown, err := telemetry.InitOTLP(ctx, "ailang-server")
if err != nil {
log.Printf("OTEL init failed: %v", err)
} else {
defer shutdown(ctx)
}
If environment variables are not set, InitOTLP returns a no-op shutdown function and nil error, allowing the application to run without telemetry.
Index ¶
- Variables
- func CategorizeError(err error) string
- func ExtractCorrelationIDs() (taskID, sessionID string)
- func ExtractTraceContext(ctx context.Context) context.Context
- func ExtractTraceContextFromEnv(ctx context.Context, env []string) context.Context
- func GoogleCloudProject() string
- func HasTraceContext(ctx context.Context) bool
- func InjectCorrelationIDs(env []string, taskID, sessionID string) []string
- func InjectTraceContext(ctx context.Context, env []string) []string
- func IsDualExportEnabled() bool
- func IsEnabled() bool
- func IsGoogleCloudEnabled() bool
- func IsTraceRecordingEnabled() bool
- func LineSnippet(source string, lineNum int, maxLen int) string
- func NewEffectSpanWrapper() effects.SpanWrapperFunc
- func NewResource(serviceName string) (*resource.Resource, error)
- func RecordSpan(spanName string)
- func SetTraceRecordingEnabled(enabled bool)
- func ShortHash(content string, length int) string
- func StartSpan(ctx context.Context, tracer trace.Tracer, spanName string, ...) (context.Context, trace.Span)
- func Tracer(name string) trace.Tracer
- func Truncate(s string, maxLen int) string
- type ErrorCategory
- type ShutdownFunc
- func Init(ctx context.Context, serviceName string) (ShutdownFunc, error)
- func InitDual(ctx context.Context, serviceName string) (ShutdownFunc, error)
- func InitGoogleCloudTrace(ctx context.Context, serviceName string) (ShutdownFunc, error)
- func InitOTLP(ctx context.Context, serviceName string) (ShutdownFunc, error)
Constants ¶
This section is empty.
Variables ¶
var Version = "dev"
Version is set at build time via ldflags.
Functions ¶
func CategorizeError ¶
CategorizeError determines the category of an error for trace filtering. Categories help users quickly filter traces by error type.
func ExtractCorrelationIDs ¶
func ExtractCorrelationIDs() (taskID, sessionID string)
ExtractCorrelationIDs reads AILANG-specific correlation IDs from environment. Returns the task ID and session ID if present, empty strings otherwise.
These IDs can be recorded as span attributes for post-run trace correlation.
func ExtractTraceContext ¶
ExtractTraceContext reads W3C trace context from environment variables. Returns a context with the extracted trace context, or the original context if no trace context is found in the environment.
This enables `ailang run` and other commands to participate in distributed traces when spawned as subprocesses. The function reads TRACEPARENT and TRACESTATE from the process environment.
Example:
ctx := context.Background() ctx = telemetry.ExtractTraceContext(ctx) // ctx now contains parent trace context if TRACEPARENT was set
func ExtractTraceContextFromEnv ¶
ExtractTraceContextFromEnv reads W3C trace context from a provided environment slice. This is useful when you have an explicit environment rather than os.Environ().
Returns a context with the extracted trace context, or the original context if no trace context is found.
func GoogleCloudProject ¶
func GoogleCloudProject() string
GoogleCloudProject returns the configured Google Cloud project for telemetry. Priority: OTLP_GOOGLE_CLOUD_PROJECT > GOOGLE_CLOUD_PROJECT
func HasTraceContext ¶
HasTraceContext checks if the current context has valid trace context. Returns true if a trace ID is present in the context.
func InjectCorrelationIDs ¶
InjectCorrelationIDs adds AILANG-specific correlation IDs to environment. These serve as fallback correlation when TRACEPARENT isn't supported by intermediate processes.
Injected variables:
- AILANG_TASK_ID: Coordinator task identifier
- AILANG_SESSION_ID: Executor session identifier
These IDs can be used to query related traces even when parent-child relationships aren't preserved.
func InjectTraceContext ¶
InjectTraceContext adds W3C trace context to environment variables. Returns the updated environment slice with TRACEPARENT and TRACESTATE added.
This enables distributed tracing across subprocess boundaries. When AILANG spawns external CLI tools (Claude Code, Gemini CLI), those tools receive the trace context via environment variables. Even if the CLI tools don't use TRACEPARENT directly, they pass it through to their child processes (like `ailang run`), enabling end-to-end trace linking.
Injected variables:
- TRACEPARENT: W3C trace context (00-{trace_id}-{span_id}-{flags})
- TRACESTATE: Vendor-specific state (if present)
Example:
env := os.Environ() env = telemetry.InjectTraceContext(ctx, env) cmd.Env = env
func IsDualExportEnabled ¶
func IsDualExportEnabled() bool
IsDualExportEnabled returns true if both GCP and OTLP are configured. This enables sending traces to both destinations simultaneously.
func IsGoogleCloudEnabled ¶
func IsGoogleCloudEnabled() bool
IsGoogleCloudEnabled returns true if Google Cloud Trace is configured. Matches Gemini CLI convention: OTLP_GOOGLE_CLOUD_PROJECT takes precedence.
func IsTraceRecordingEnabled ¶
func IsTraceRecordingEnabled() bool
IsTraceRecordingEnabled returns whether trace recording is enabled.
func LineSnippet ¶
LineSnippet extracts a snippet of source code around the given line number. Returns at most maxLen characters, centered on the target line.
func NewEffectSpanWrapper ¶
func NewEffectSpanWrapper() effects.SpanWrapperFunc
NewEffectSpanWrapper returns a SpanWrapperFunc that wraps each effect operation with an OTEL span. Returns nil if telemetry is not configured, ensuring zero overhead when OTEL is disabled.
The returned wrapper:
- Creates a span named "effect.<effectName>.<opName>"
- Sets pre-call attributes (effect name, op, arg count)
- Adds per-effect enrichment (e.g., Process command, FS path, Net URL)
- Executes the effect operation
- Sets post-call status and per-effect result attributes
- Ends the span
func NewResource ¶
NewResource creates a resource with service information. The serviceName is required; other attributes are automatically populated. Includes process.cwd for debugging path-related issues (module resolution, etc.) Also parses OTEL_RESOURCE_ATTRIBUTES for task hierarchy context (M-TASK-HIERARCHY).
func RecordSpan ¶
func RecordSpan(spanName string)
RecordSpan records a span name to TraceRegistry if recording is enabled. Call this after tracer.Start() to bridge OTEL spans to TraceRegistry.
Example:
ctx, span := tracer.Start(ctx, "compile.parse")
telemetry.RecordSpan("compile.parse")
defer span.End()
func SetTraceRecordingEnabled ¶
func SetTraceRecordingEnabled(enabled bool)
SetTraceRecordingEnabled allows programmatic control of trace recording. Primarily used for testing.
func ShortHash ¶
ShortHash returns a short hex-encoded hash of the content. Useful for deduplication without storing full content.
func StartSpan ¶
func StartSpan(ctx context.Context, tracer trace.Tracer, spanName string, opts ...trace.SpanStartOption) (context.Context, trace.Span)
StartSpan creates a span and records it to TraceRegistry if enabled. This is the recommended way to create spans when trace recording may be enabled.
Example:
ctx, span := telemetry.StartSpan(ctx, tracer, "compile.parse") defer span.End()
Types ¶
type ErrorCategory ¶
type ErrorCategory string
ErrorCategory represents categories of errors for filtering in traces.
const ( ErrorCategoryParse ErrorCategory = "parse_error" ErrorCategoryType ErrorCategory = "type_error" ErrorCategoryModule ErrorCategory = "module_error" ErrorCategoryRuntime ErrorCategory = "runtime_error" ErrorCategoryAPI ErrorCategory = "api_error" ErrorCategoryTimeout ErrorCategory = "timeout" ErrorCategoryUnknown ErrorCategory = "unknown" )
type ShutdownFunc ¶
ShutdownFunc is a function that shuts down telemetry providers.
func Init ¶
func Init(ctx context.Context, serviceName string) (ShutdownFunc, error)
Init initializes telemetry based on environment configuration.
Priority: 1. Both GOOGLE_CLOUD_PROJECT + OTEL_EXPORTER_OTLP_ENDPOINT → Dual export 2. GOOGLE_CLOUD_PROJECT only → Google Cloud Trace 3. OTEL_EXPORTER_OTLP_ENDPOINT only → Generic OTLP 4. Neither → No-op (telemetry disabled)
func InitDual ¶
func InitDual(ctx context.Context, serviceName string) (ShutdownFunc, error)
InitDual initializes OpenTelemetry with both Google Cloud Trace and OTLP exporters. Traces are sent to both destinations simultaneously.
Environment variables:
- GOOGLE_CLOUD_PROJECT or OTLP_GOOGLE_CLOUD_PROJECT: GCP project for Cloud Trace
- OTEL_EXPORTER_OTLP_ENDPOINT: OTLP collector endpoint (e.g., Jaeger, Honeycomb)
Example:
export GOOGLE_CLOUD_PROJECT=my-project export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 shutdown, err := telemetry.InitDual(ctx, "my-service")
func InitGoogleCloudTrace ¶
func InitGoogleCloudTrace(ctx context.Context, serviceName string) (ShutdownFunc, error)
InitGoogleCloudTrace initializes OpenTelemetry with Google Cloud Trace exporter.
This uses Application Default Credentials (ADC) for authentication. Environment variables (matching Gemini CLI convention):
- OTLP_GOOGLE_CLOUD_PROJECT: Telemetry-specific project (takes precedence)
- GOOGLE_CLOUD_PROJECT: General GCP project (fallback)
Traces will appear in: https://console.cloud.google.com/traces/explorer?project=YOUR_PROJECT
Example:
# Option 1: Same project for inference and telemetry
export GOOGLE_CLOUD_PROJECT=multivac-internal-dev
# Option 2: Separate telemetry project
export OTLP_GOOGLE_CLOUD_PROJECT=my-telemetry-project
shutdown, err := telemetry.InitGoogleCloudTrace(ctx, "ailang-coordinator")
if err != nil {
log.Fatal(err)
}
defer shutdown(ctx)
func InitOTLP ¶
func InitOTLP(ctx context.Context, serviceName string) (ShutdownFunc, error)
InitOTLP initializes OpenTelemetry with OTLP exporters for traces and metrics.
It returns a shutdown function that should be called on application exit to flush pending telemetry data.
If the OTEL_EXPORTER_OTLP_ENDPOINT environment variable is not set, this function returns a no-op shutdown and nil error, allowing the application to run without telemetry.
Example:
shutdown, err := telemetry.InitOTLP(ctx, "ailang-coordinator")
if err != nil {
log.Fatal(err)
}
defer shutdown(ctx)
Source Files