trace

type DiscardTracer struct{}

type Event struct {
	// Kind identifies the ADK operation.
	Kind Kind
	// Time is the event timestamp. Implementations use time.Now when it is zero.
	Time time.Time
	// Duration is an optional measured operation duration.
	Duration time.Duration

	// RunID identifies one Runner.Run call.
	RunID string
	// TurnID groups all events produced by one Runner.Run call.
	TurnID string
	// SessionID identifies the session that owns the operation.
	SessionID string
	// AppID identifies the application or tenant that owns the session.
	AppID string
	// UserID identifies the end user that owns the session.
	UserID string

	// AgentName identifies the agent involved in the operation.
	AgentName string
	// Model identifies the LLM model involved in the operation.
	Model string
	// Iteration is the 1-based LLM-agent loop iteration.
	Iteration int
	// Stream reports whether the LLM call used streaming mode.
	Stream bool

	// EventID identifies the persisted event involved in the operation.
	EventID int64
	// EventAuthor is the ADK event author.
	EventAuthor string
	// EventRole is the content role of the ADK event.
	EventRole model.Role
	// EventCount reports how many events were processed by the operation.
	EventCount int
	// Partial reports whether the event is a streaming fragment.
	Partial bool

	// ToolName identifies the tool involved in the operation.
	ToolName string
	// ToolCallID identifies the model-requested tool call.
	ToolCallID string
	// ToolIndex is the 0-based tool-call index within one assistant response.
	ToolIndex int

	// FinishReason reports why the LLM stopped generating.
	FinishReason model.FinishReason
	// PromptTokens reports provider input token usage.
	PromptTokens int64
	// CompletionTokens reports provider output token usage.
	CompletionTokens int64
	// TotalTokens reports provider total token usage.
	TotalTokens int64
	// PartialResponses counts partial streaming responses observed in an LLM call.
	PartialResponses int
	// StoppedEarly reports that downstream iteration stopped before completion.
	StoppedEarly bool
	// ToolOutcome reports the completed outcome of a tool call.
	ToolOutcome ToolOutcome
	// Err is the Go error that ended the operation, if any.
	Err error
	// Attributes carries implementation-specific fields.
	Attributes map[string]any
}

type Kind string

type RunInfo struct {
	// RunID identifies one Runner.Run call.
	RunID string
	// TurnID groups all events produced by one Runner.Run call.
	TurnID string
	// SessionID identifies the session passed to Runner.Run.
	SessionID string
	// AppID identifies the application or tenant that owns the session.
	AppID string
	// UserID identifies the end user that owns the session.
	UserID string
}

type Span interface {
	// AddEvent records an instantaneous event on the span.
	AddEvent(ctx context.Context, event Event)
	// End completes the span.
	End(ctx context.Context, event Event)
}

type ToolOutcome string

type Tracer interface {
	// Start starts a span for event and returns a context carrying that span.
	Start(ctx context.Context, event Event) (context.Context, Span)
}