Documentation
¶
Overview ¶
Package otel implements Surface 3 — OpenTelemetry GenAI export. It emits one span per governed model call carrying the attribute set pinned in api/v1/otel-genai.md (gen_ai.* + riskkernel.*), so a run becomes observable in whatever OTLP backend the user already runs (Grafana Tempo, SigNoz, Jaeger, Honeycomb, Datadog, …).
It is OFF unless the user configures an OTLP endpoint. RiskKernel never emits telemetry on its own — spans go only to the endpoint the user points it at. This is the only package besides internal/provider permitted outbound network.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Call ¶
type Call struct {
RunID string
RunName string // the run's name, emitted for spend attribution
Metadata map[string]string // user-supplied run tags (team/user/feature/…)
StepIndex int32
Provider string
Operation string // e.g. "chat"
RequestModel string
ResponseModel string
MaxTokens int
Temperature *float64
PromptTokens int64
OutputTokens int64
CostUSD float64
Priced bool
FinishReason string
ResponseID string
BudgetTokensLimit int64
BudgetTokensRemaining int64
BudgetDollarsLimit float64
BudgetDollarsRemaining float64
HaltReason string // empty if none
Err error // non-nil if the call failed
Start time.Time
End time.Time
}
Call is the data for one governed model-call span.
type Ingress ¶ added in v0.7.0
type Ingress struct {
// contains filtered or unexported fields
}
Ingress is the OTLP/HTTP trace receiver — the consume side of Surface 3. It accepts GenAI spans from apps already instrumented (OpenLLMetry, the OpenAI Agents SDK, the Vercel AI SDK), correlates each model-call span to a governed run by riskkernel.run.id, and meters its token usage and cost into the ledger. This lets RiskKernel make spend visible for apps it never directly proxied.
Scope is observe + meter: a consumed span records against the run's ledger but does not retroactively block a call that already happened (governing consumed spans is a separate, future step). The receiver is off by default and mounted only when RISKKERNEL_OTEL_INGRESS_ENABLED is set.
func NewIngress ¶ added in v0.7.0
NewIngress constructs the OTLP trace receiver. mgr and prices must be non-nil.
func (*Ingress) HandleTraces ¶ added in v0.7.0
func (in *Ingress) HandleTraces(w http.ResponseWriter, r *http.Request)
HandleTraces implements POST /v1/traces, the standard OTLP/HTTP traces path — point any OTLP exporter (OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:7070) at it. It accepts protobuf (application/x-protobuf, the OTLP default) or JSON (application/json), meters the GenAI model-call spans it recognizes, and replies with an OTLP ExportTraceServiceResponse in the request's encoding.
type ToolCall ¶ added in v0.4.0
type ToolCall struct {
RunID string
StepIndex int32
Tool string
SideEffect string // "" for read-only
Status string // approved | blocked | denied | timeout
Start time.Time
End time.Time
}
ToolCall is a governed MCP tool call to record as a span.
type Tracer ¶
type Tracer struct {
// contains filtered or unexported fields
}
Tracer emits governed-call spans. The zero value and Disabled() are safe no-ops.
func Disabled ¶
func Disabled() *Tracer
Disabled returns a no-op Tracer (used when no OTLP endpoint is configured and in tests).
func New ¶
New builds a Tracer. If cfg.Endpoint is empty it returns a disabled no-op Tracer (no exporter, no network). Otherwise it wires an OTLP exporter (grpc or http) to the configured endpoint.
func NewWithProcessor ¶
func NewWithProcessor(sp sdktrace.SpanProcessor, serviceName string) *Tracer
NewWithProcessor builds an enabled Tracer around a caller-supplied span processor — useful for custom pipelines and for tests (e.g. an in-memory span recorder).
func (*Tracer) RecordCall ¶
RecordCall emits a span for one governed model call. No-op when disabled.
func (*Tracer) RecordToolCall ¶ added in v0.4.0
RecordToolCall emits a span for one governed MCP tool call, so tool governance — allowlist blocks, approval denials, approved calls — is visible alongside model calls in the user's OTLP backend. No-op when disabled.
Source Files