telemetry

package

v2.5.1 Latest Latest Go to latest Published: Jul 29, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation ¶

Index ¶

Constants
Variables
func DetachContext(ctx context.Context) context.Context
func NewLogSpanProcessor(log LogService) sdktrace.SpanProcessor
func NewTurnIDGenerator() sdktrace.IDGenerator
func SpanContextForTurn(turnID string) trace.SpanContext
func SpanFromContext(ctx context.Context) trace.Span
func Tracer() trace.Tracer
func WithLLMAttributes(provider, model, operation string, streaming bool) trace.SpanStartOption
func WithTurnID(ctx context.Context, turnID string) context.Context
type LogService
type OutputMode
type ShutdownFunc
- func Init(ctx context.Context, serviceName, serviceVersion string, mode OutputMode, ...) (ShutdownFunc, error)

Constants ¶

const TracerName = "github.com/mattermost/mattermost-plugin-ai"

Variables ¶

View Source

var (
	LLMProvider  = attribute.Key("agents.llm.provider")
	LLMModel     = attribute.Key("agents.llm.model")
	LLMOperation = attribute.Key("agents.llm.operation")
	LLMStreaming = attribute.Key("agents.llm.streaming")

	LLMInputTokens       = attribute.Key("agents.llm.input_tokens")
	LLMOutputTokens      = attribute.Key("agents.llm.output_tokens")
	LLMCachedReadTokens  = attribute.Key("agents.llm.cached_read_tokens")
	LLMCachedWriteTokens = attribute.Key("agents.llm.cached_write_tokens")
	LLMReasoningTokens   = attribute.Key("agents.llm.reasoning_tokens")
	LLMCost              = attribute.Key("agents.llm.cost")

	// Routing — which bifrost code path the request took.
	LLMPath            = attribute.Key("agents.llm.path")              // "chat" | "responses"
	LLMUseResponsesAPI = attribute.Key("agents.llm.use_responses_api") // bot/service-level toggle

	// Reasoning — what (if anything) was attached to the outbound request.
	LLMReasoningEffort    = attribute.Key("agents.llm.reasoning.effort")
	LLMReasoningMaxTokens = attribute.Key("agents.llm.reasoning.max_tokens")
	LLMReasoningSent      = attribute.Key("agents.llm.reasoning.sent") // true when the request includes a reasoning block

	// Bifrost error surface — populated when a request fails so opaque
	// "bifrost error: …" log lines can be correlated with status/type/code.
	LLMBifrostStatusCode    = attribute.Key("agents.llm.bifrost.status_code")
	LLMBifrostErrorType     = attribute.Key("agents.llm.bifrost.error_type")
	LLMBifrostErrorCode     = attribute.Key("agents.llm.bifrost.error_code")
	LLMBifrostErrorProvider = attribute.Key("agents.llm.bifrost.error_provider")
	LLMBifrostIsBifrostErr  = attribute.Key("agents.llm.bifrost.is_bifrost_error")

	// Per-source breakdown of agents.llm.input_tokens, derived from the
	// request and emitted on the LLM-call span. One attribute per source.
	LLMTokensSystem      = attribute.Key("agents.llm.tokens.system")
	LLMTokensHistory     = attribute.Key("agents.llm.tokens.history")
	LLMTokensToolDefs    = attribute.Key("agents.llm.tokens.tool_defs")
	LLMTokensToolResults = attribute.Key("agents.llm.tokens.tool_results")
	LLMTokensImages      = attribute.Key("agents.llm.tokens.images")
)

Attribute keys for LLM operations

View Source

var (
	AgentName = attribute.Key("agents.agent.name")
	AgentID   = attribute.Key("agents.agent.id")
)

Attribute keys for agent context

View Source

var (
	ToolName   = attribute.Key("agents.tool.name")
	ToolID     = attribute.Key("agents.tool.id")
	ToolStatus = attribute.Key("agents.tool.status")
)

Attribute keys for tool operations

View Source

var (
	MCPServer = attribute.Key("agents.mcp.server")
	MCPTool   = attribute.Key("agents.mcp.tool")
)

Attribute keys for MCP operations

View Source

var (
	UserID           = attribute.Key("agents.user.id")
	ChannelID        = attribute.Key("agents.channel.id")
	PostID           = attribute.Key("agents.post.id")
	ThreadRootPostID = attribute.Key("agents.thread.root_post.id")
)

Attribute keys for Mattermost entities

Functions ¶

func DetachContext ¶

func DetachContext(ctx context.Context) context.Context

DetachContext returns a context whose lifetime is independent of ctx but preserves the active OpenTelemetry span. Use this when handing a request context to background work (post streaming, async processing) that must continue after the originating HTTP handler returns. Without it, the request context's cancellation propagates into the background goroutine and truncates the work.

func NewLogSpanProcessor ¶

func NewLogSpanProcessor(log LogService) sdktrace.SpanProcessor

NewLogSpanProcessor returns a SpanProcessor that emits one log entry per finished span. Spans whose status code is Error are logged at Error level; everything else at Info.

func NewTurnIDGenerator ¶

func NewTurnIDGenerator() sdktrace.IDGenerator

NewTurnIDGenerator returns an IDGenerator suitable for sdktrace.WithIDGenerator that produces deterministic IDs derived from the turn ID stashed in ctx via WithTurnID, and falls back to the SDK's default random generator otherwise.

func SpanContextForTurn ¶

func SpanContextForTurn(turnID string) trace.SpanContext

SpanContextForTurn returns a valid SpanContext anchored to the trace associated with turnID, suitable for use as a trace.Link target. The SpanID matches what the run's root span would have, so a link points to a real, locatable trace in Tempo even though the link's exact span ID won't necessarily resolve.

func SpanFromContext ¶

func SpanFromContext(ctx context.Context) trace.Span

SpanFromContext extracts the current span from context.

func Tracer ¶

func Tracer() trace.Tracer

Tracer returns a named tracer from the global provider.

func WithLLMAttributes ¶

func WithLLMAttributes(provider, model, operation string, streaming bool) trace.SpanStartOption

WithLLMAttributes returns a SpanStartOption with standard LLM attributes.

func WithTurnID ¶

func WithTurnID(ctx context.Context, turnID string) context.Context

WithTurnID returns a ctx that, when used to start a new root span (via trace.WithNewRoot), will produce a TraceID deterministically derived from turnID. Empty turnID is a no-op.

Types ¶

type LogService ¶

type LogService interface {
	Info(message string, keyValuePairs ...any)
	Error(message string, keyValuePairs ...any)
}

LogService is the subset of pluginapi.LogService that the log span processor needs. Defined locally so tests can supply a fake without pulling in the plugin API.

type OutputMode ¶

type OutputMode string

OutputMode selects where finished spans are sent.

const (
	// OutputModeOff disables tracing entirely (no-op TracerProvider).
	OutputModeOff OutputMode = "off"
	// OutputModeLogs writes spans to the Mattermost server log via
	// pluginapi.LogService. No collector required.
	OutputModeLogs OutputMode = "logs"
	// OutputModeOTLP exports spans to an OTLP gRPC endpoint such as
	// Grafana Tempo or Jaeger.
	OutputModeOTLP OutputMode = "otlp"
)

type ShutdownFunc ¶

type ShutdownFunc func(context.Context) error

ShutdownFunc is returned by Init and must be called to flush pending spans.

func Init ¶

func Init(ctx context.Context, serviceName, serviceVersion string, mode OutputMode, endpoint string, log LogService) (ShutdownFunc, error)

Init sets up the global TracerProvider for the selected output mode.

OutputModeOff registers a no-op provider.
OutputModeLogs writes finished spans through log.
OutputModeOTLP exports spans to the OTLP gRPC endpoint.

log is required for OutputModeLogs; endpoint is required for OutputModeOTLP.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL