Documentation
¶
Index ¶
- Constants
- type ActivityErrorSummary
- type ActivityMetricPeek
- type ActivityThroughput
- type ActivityTraceSummary
- type AddOTLPPortInput
- type AddOTLPPortOutput
- type ClearDataInput
- type ClearDataOutput
- type CreateSnapshotInput
- type CreateSnapshotOutput
- type DataSummary
- type FileSourceInfo
- type GetOTLPEndpointInput
- type GetOTLPEndpointOutput
- type GetSnapshotDataInput
- type GetSnapshotDataOutput
- type GetStatsInput
- type GetStatsOutput
- type ListFileSourcesInput
- type ListFileSourcesOutput
- type LogStorageStats
- type LogSummary
- type ManageSnapshotsInput
- type ManageSnapshotsOutput
- type MetricStorageStats
- type MetricSummary
- type QueryInput
- type QueryOutput
- type QuerySummary
- type RecentActivityInput
- type RecentActivityOutput
- type RemoveFileSourceInput
- type RemoveFileSourceOutput
- type RemoveOTLPPortInput
- type RemoveOTLPPortOutput
- type Server
- func (s *Server) AddFileSource(ctx context.Context, directory string, activeOnly bool) error
- func (s *Server) FileSourceStats() []filereader.Stats
- func (s *Server) ListFileSources() []string
- func (s *Server) MCPServer() *mcp.Server
- func (s *Server) RemoveFileSource(directory string) error
- func (s *Server) Run(ctx context.Context) error
- func (s *Server) Shutdown()
- type ServerOptions
- type SetFileSourceInput
- type SetFileSourceOutput
- type StatusInput
- type StatusOutput
- type StorageStats
- type TimeRange
- type TraceSummary
Constants ¶
const DefaultWindowDurationMs = 60000 // 1 minute
DefaultWindowDurationMs is the default window duration for activity summary.
const MaxMetricPeekNames = 20
MaxMetricPeekNames is the maximum number of metric names allowed in a peek request.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ActivityErrorSummary ¶
type ActivityErrorSummary struct {
TraceID string `json:"trace_id" jsonschema:"Trace ID"`
Service string `json:"service" jsonschema:"Service name"`
SpanName string `json:"span_name" jsonschema:"Span name where error occurred"`
ErrorMsg string `json:"error_msg" jsonschema:"Error message"`
Timestamp uint64 `json:"timestamp_unix_nano" jsonschema:"Error timestamp (Unix nanoseconds)"`
}
type ActivityMetricPeek ¶
type ActivityMetricPeek struct {
Name string `json:"name" jsonschema:"Metric name"`
Type string `json:"type" jsonschema:"Metric type"`
Value *float64 `json:"value,omitempty" jsonschema:"Current value (Gauge/Sum)"`
Count *uint64 `json:"count,omitempty" jsonschema:"Count (Histogram)"`
Sum *float64 `json:"sum,omitempty" jsonschema:"Sum (Histogram)"`
Min *float64 `json:"min,omitempty" jsonschema:"Min value (Histogram)"`
Max *float64 `json:"max,omitempty" jsonschema:"Max value (Histogram)"`
Percentiles map[string]float64 `json:"percentiles,omitempty" jsonschema:"Percentiles: p50, p95, p99 (Histogram)"`
}
type ActivityThroughput ¶
type ActivityTraceSummary ¶
type ActivityTraceSummary struct {
TraceID string `json:"trace_id" jsonschema:"Trace ID"`
Service string `json:"service" jsonschema:"Service name"`
RootSpan string `json:"root_span" jsonschema:"Root span name (or first span seen)"`
Status string `json:"status" jsonschema:"Status: OK, ERROR, or UNSET"`
DurationMs float64 `json:"duration_ms" jsonschema:"Duration in milliseconds"`
ErrorMsg string `json:"error_msg,omitempty" jsonschema:"Error message if status is ERROR"`
}
type AddOTLPPortInput ¶
type AddOTLPPortInput struct {
Port int `json:"port" jsonschema:"Port to add (1-65535)"`
}
type AddOTLPPortOutput ¶
type ClearDataInput ¶
type ClearDataInput struct{}
type ClearDataOutput ¶
type ClearDataOutput struct {
Message string `json:"message" jsonschema:"Confirmation message"`
}
type CreateSnapshotInput ¶
type CreateSnapshotInput struct {
Name string `json:"name" jsonschema:"Snapshot name (e.g. 'before-deploy', 'test-start')"`
}
type CreateSnapshotOutput ¶
type CreateSnapshotOutput struct {
Name string `json:"name" jsonschema:"Snapshot name"`
TracePos int `json:"trace_position" jsonschema:"Current trace buffer position"`
LogPos int `json:"log_position" jsonschema:"Current log buffer position"`
MetricPos int `json:"metric_position" jsonschema:"Current metric buffer position"`
Message string `json:"message" jsonschema:"Success message"`
}
type DataSummary ¶
type DataSummary struct {
TraceCount int `json:"trace_count" jsonschema:"Number of spans"`
LogCount int `json:"log_count" jsonschema:"Number of logs"`
MetricCount int `json:"metric_count" jsonschema:"Number of metrics"`
Services []string `json:"services" jsonschema:"Distinct services"`
TraceIDs []string `json:"trace_ids" jsonschema:"Distinct trace IDs"`
LogSeverities map[string]int `json:"log_severities" jsonschema:"Log severity counts"`
MetricNames []string `json:"metric_names" jsonschema:"Distinct metric names"`
}
type FileSourceInfo ¶
type GetOTLPEndpointInput ¶
type GetOTLPEndpointInput struct{}
type GetOTLPEndpointOutput ¶
type GetOTLPEndpointOutput struct {
Endpoint string `json:"endpoint" jsonschema:"OTLP gRPC endpoint address (accepts traces, logs, and metrics)"`
Protocol string `json:"protocol" jsonschema:"Protocol type (grpc)"`
EnvironmentVars map[string]string `json:"environment_vars" jsonschema:"Suggested environment variables for configuring applications"`
}
type GetSnapshotDataInput ¶
type GetSnapshotDataOutput ¶
type GetSnapshotDataOutput struct {
StartSnapshot string `json:"start_snapshot" jsonschema:"Start snapshot name"`
EndSnapshot string `json:"end_snapshot" jsonschema:"End snapshot name"`
TimeRange TimeRange `json:"time_range" jsonschema:"Time window of the data"`
Traces []TraceSummary `json:"traces" jsonschema:"All traces in time range"`
Logs []LogSummary `json:"logs" jsonschema:"All logs in time range"`
Metrics []MetricSummary `json:"metrics" jsonschema:"All metrics in time range"`
Summary DataSummary `json:"summary" jsonschema:"Data summary"`
}
type GetStatsInput ¶
type GetStatsInput struct{}
type GetStatsOutput ¶
type GetStatsOutput struct {
Traces StorageStats `json:"traces" jsonschema:"Trace storage statistics"`
Logs LogStorageStats `json:"logs" jsonschema:"Log storage statistics"`
Metrics MetricStorageStats `json:"metrics" jsonschema:"Metric storage statistics"`
Snapshots int `json:"snapshot_count" jsonschema:"Number of snapshots"`
}
type ListFileSourcesInput ¶
type ListFileSourcesInput struct{}
type ListFileSourcesOutput ¶
type ListFileSourcesOutput struct {
Sources []FileSourceInfo `json:"sources" jsonschema:"Active file sources"`
Count int `json:"count" jsonschema:"Number of active file sources"`
}
type LogStorageStats ¶
type LogStorageStats struct {
LogCount int `json:"log_count" jsonschema:"Current number of logs"`
Capacity int `json:"capacity" jsonschema:"Maximum logs capacity"`
TraceCount int `json:"trace_count" jsonschema:"Logs linked to traces"`
ServiceCount int `json:"service_count" jsonschema:"Distinct services"`
Severities map[string]int `json:"severities" jsonschema:"Severity level counts"`
}
type LogSummary ¶
type LogSummary struct {
TraceID string `json:"trace_id,omitempty" jsonschema:"Associated trace ID (hex)"`
SpanID string `json:"span_id,omitempty" jsonschema:"Associated span ID (hex)"`
ServiceName string `json:"service_name" jsonschema:"Service name"`
Severity string `json:"severity" jsonschema:"Severity text (INFO, ERROR, etc)"`
SeverityNum int32 `json:"severity_number" jsonschema:"Severity number"`
Body string `json:"body" jsonschema:"Log message body"`
Timestamp uint64 `json:"timestamp_unix_nano" jsonschema:"Timestamp (Unix nanoseconds)"`
Attributes map[string]any `json:"attributes,omitempty" jsonschema:"Log attributes"`
}
type ManageSnapshotsInput ¶
type ManageSnapshotsOutput ¶
type MetricStorageStats ¶
type MetricStorageStats struct {
MetricCount int `json:"metric_count" jsonschema:"Current number of metrics"`
Capacity int `json:"capacity" jsonschema:"Maximum metrics capacity"`
UniqueNames int `json:"unique_names" jsonschema:"Distinct metric names"`
ServiceCount int `json:"service_count" jsonschema:"Distinct services"`
TypeCounts map[string]int `json:"type_counts" jsonschema:"Counts by metric type"`
}
type MetricSummary ¶
type MetricSummary struct {
MetricName string `json:"metric_name" jsonschema:"Metric name"`
ServiceName string `json:"service_name" jsonschema:"Service name"`
MetricType string `json:"metric_type" jsonschema:"Metric type (Gauge, Sum, Histogram, etc)"`
Timestamp uint64 `json:"timestamp_unix_nano" jsonschema:"Timestamp (Unix nanoseconds)"`
Value *float64 `json:"value,omitempty" jsonschema:"Numeric value (for Gauge/Sum)"`
Count *uint64 `json:"count,omitempty" jsonschema:"Count (for Histogram)"`
Sum *float64 `json:"sum,omitempty" jsonschema:"Sum (for Histogram)"`
DataPoints int `json:"data_point_count" jsonschema:"Number of data points"`
}
type QueryInput ¶
type QueryInput struct {
// Basic filters
ServiceName string `json:"service_name,omitempty" jsonschema:"Filter by service name"`
TraceID string `json:"trace_id,omitempty" jsonschema:"Filter by trace ID (hex format)"`
SpanName string `json:"span_name,omitempty" jsonschema:"Filter by span operation name"`
LogSeverity string `json:"log_severity,omitempty" jsonschema:"Filter logs by severity (INFO, WARN, ERROR, etc)"`
MetricNames []string `json:"metric_names,omitempty" jsonschema:"Filter metrics by names"`
StartSnapshot string `json:"start_snapshot,omitempty" jsonschema:"Start of time range (snapshot name)"`
EndSnapshot string `json:"end_snapshot,omitempty" jsonschema:"End of time range (snapshot name, empty = current)"`
Limit int `json:"limit,omitempty" jsonschema:"Maximum results per signal type (0 = no limit)"`
// Status filters (NEW)
ErrorsOnly bool `json:"errors_only,omitempty" jsonschema:"Only return spans with error status (shortcut for span_status=ERROR)"`
SpanStatus string `json:"span_status,omitempty" jsonschema:"Filter by span status: OK, ERROR, or UNSET"`
// Duration filters in nanoseconds (NEW)
MinDurationNs *uint64 `json:"min_duration_ns,omitempty" jsonschema:"Minimum span duration in nanoseconds (e.g., 500000000 for 500ms)"`
MaxDurationNs *uint64 `json:"max_duration_ns,omitempty" jsonschema:"Maximum span duration in nanoseconds"`
// Attribute filters (NEW)
HasAttribute string `json:"has_attribute,omitempty" jsonschema:"Filter spans/logs that have this attribute key (e.g., 'http.status_code')"`
AttributeEquals map[string]string `json:"attribute_equals,omitempty" jsonschema:"Filter by attribute key-value pairs (e.g., {'http.status_code': '500'})"`
}
type QueryOutput ¶
type QueryOutput struct {
Traces []TraceSummary `json:"traces" jsonschema:"Matching trace spans"`
Logs []LogSummary `json:"logs" jsonschema:"Matching log records"`
Metrics []MetricSummary `json:"metrics" jsonschema:"Matching metrics"`
Summary QuerySummary `json:"summary" jsonschema:"Query result summary"`
}
type QuerySummary ¶
type QuerySummary struct {
TraceCount int `json:"trace_count" jsonschema:"Number of spans returned"`
LogCount int `json:"log_count" jsonschema:"Number of logs returned"`
MetricCount int `json:"metric_count" jsonschema:"Number of metrics returned"`
Services []string `json:"services" jsonschema:"Distinct services in results"`
TraceIDs []string `json:"trace_ids" jsonschema:"Distinct trace IDs in results"`
}
type RecentActivityInput ¶
type RecentActivityInput struct {
MetricNames []string `json:"metric_names,omitempty" jsonschema:"Metric names to peek (max 20, empty = none)"`
}
type RecentActivityOutput ¶
type RecentActivityOutput struct {
RecentTraces []ActivityTraceSummary `json:"recent_traces" jsonschema:"Most recent 5 traces"`
RecentErrors []ActivityErrorSummary `json:"recent_errors" jsonschema:"Most recent 5 errors (separate from traces)"`
Throughput ActivityThroughput `json:"throughput" jsonschema:"Throughput counters (caller computes rates)"`
MetricsPeek []ActivityMetricPeek `json:"metrics_peek,omitempty" jsonschema:"Current values for requested metrics"`
WindowDurationMs int64 `json:"window_duration_ms" jsonschema:"Window duration in milliseconds"`
}
type RemoveFileSourceInput ¶
type RemoveFileSourceInput struct {
Directory string `json:"directory" jsonschema:"Directory to stop watching"`
}
type RemoveFileSourceOutput ¶
type RemoveOTLPPortInput ¶
type RemoveOTLPPortInput struct {
Port int `json:"port" jsonschema:"Port to remove (1-65535)"`
}
type RemoveOTLPPortOutput ¶
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps the MCP server with observability storage and OTLP receiver. It provides snapshot-first tools for agents to query telemetry data across all signal types.
func NewServer ¶
func NewServer(obsStorage *storage.ObservabilityStorage, otlpReceiver *otlpreceiver.UnifiedServer, opts ...ServerOptions) (*Server, error)
NewServer creates a new MCP server that exposes snapshot-first observability tools. The otlpReceiver provides the OTLP endpoint and enables dynamic port rebinding.
func (*Server) AddFileSource ¶
AddFileSource adds a new file source that reads OTLP JSONL from a directory. When activeOnly is true, only active files (e.g., traces.jsonl) are loaded, skipping rotated archives (e.g., traces-2025-12-09T13-10-56.jsonl). Returns an error if the directory is already being watched.
func (*Server) FileSourceStats ¶
func (s *Server) FileSourceStats() []filereader.Stats
FileSourceStats returns stats for all file sources.
func (*Server) ListFileSources ¶
ListFileSources returns all active file source directories.
func (*Server) MCPServer ¶
MCPServer returns the underlying mcp.Server for use with alternative transports. This enables the server to be used with StreamableHTTPHandler for HTTP transport.
func (*Server) RemoveFileSource ¶
RemoveFileSource stops and removes a file source. The source is removed from the map under the lock, then stopped outside the lock so fs.Stop cannot block other operations.
type ServerOptions ¶
type ServerOptions struct {
Verbose bool // Enable verbose logging
}
ServerOptions configures the MCP server.
type SetFileSourceInput ¶
type SetFileSourceInput struct {
Directory string `` /* 153-byte string literal not displayed */
// ActiveOnly when true (default) only loads active files like traces.jsonl,
// skipping rotated archives like traces-2025-12-09T13-10-56.jsonl.
// Set to false to load all files including archives.
ActiveOnly *bool `json:"active_only,omitempty" jsonschema:"Only load active files, skip rotated archives (default: true)"`
}
type SetFileSourceOutput ¶
type SetFileSourceOutput struct {
Directory string `json:"directory" jsonschema:"Directory being watched"`
WatchedDirs []string `json:"watched_dirs" jsonschema:"Subdirectories being watched (traces, logs, metrics)"`
Success bool `json:"success" jsonschema:"Whether setup succeeded"`
Message string `json:"message,omitempty" jsonschema:"Additional information"`
}
type StatusInput ¶
type StatusInput struct{}
type StatusOutput ¶
type StatusOutput struct {
SpansReceived uint64 `json:"spans_received" jsonschema:"Total spans received since startup"`
LogsReceived uint64 `json:"logs_received" jsonschema:"Total logs received since startup"`
MetricsReceived uint64 `json:"metrics_received" jsonschema:"Total metrics received since startup"`
RecentErrorCount int `json:"recent_error_count" jsonschema:"Number of recent errors tracked (max 100)"`
Generation uint64 `json:"generation" jsonschema:"Change counter - incremented on any telemetry receipt"`
UptimeSeconds float64 `json:"uptime_seconds" jsonschema:"Server uptime in seconds"`
}
type StorageStats ¶
type TraceSummary ¶
type TraceSummary struct {
TraceID string `json:"trace_id" jsonschema:"Trace ID (hex)"`
SpanID string `json:"span_id" jsonschema:"Span ID (hex)"`
ParentSpanID string `json:"parent_span_id,omitempty" jsonschema:"Parent span ID (hex, empty for root)"`
ServiceName string `json:"service_name" jsonschema:"Service name"`
SpanName string `json:"span_name" jsonschema:"Span operation name"`
StartTime uint64 `json:"start_time_unix_nano" jsonschema:"Start time (Unix nanoseconds)"`
EndTime uint64 `json:"end_time_unix_nano" jsonschema:"End time (Unix nanoseconds)"`
Status string `json:"status,omitempty" jsonschema:"Span status code"`
Attributes map[string]any `json:"attributes,omitempty" jsonschema:"Span attributes"`
}