middleware

func AttachPrometheus ¶

func AttachPrometheus(s *server.Server, r *router.Router, opts ...MetricsOption) router.Middleware

AttachPrometheus registers the Prometheus middleware on the router and configures the server to emit runtime metrics to the Prometheus collector.

func OpenTelemetry ¶

func OpenTelemetry(opts ...OTelOption) router.Middleware

OpenTelemetry creates middleware that traces every Vango event.

The middleware:

• Creates a span for each event with type, target, and session ID
• Injects trace context into ctx.StdContext() for downstream calls
• Records errors and sets span status
• Records patch count as a span attribute

Example:

app := vango.NewApp(
    vango.WithMiddleware(
        middleware.OpenTelemetry(
            middleware.WithTracerName("my-app"),
            middleware.WithIncludeUserID(true),
        ),
    ),
)

The tracer uses the global OpenTelemetry tracer provider. Configure it in your main() before starting the server:

tp := sdktrace.NewTracerProvider(
    sdktrace.WithBatcher(exporter),
    sdktrace.WithResource(resource.NewWithAttributes(
        semconv.SchemaURL,
        semconv.ServiceName("my-app"),
    )),
)
otel.SetTracerProvider(tp)

func Prometheus ¶

func Prometheus(opts ...MetricsOption) router.Middleware

Prometheus creates middleware that collects Prometheus metrics for Vango events.

Metrics collected:

• vango_signal_write_violation_total: Counter of invalid signal write attempts (low-cardinality labels: operation, reason)
• vango_events_total: Counter of events by path and status
• vango_event_duration_seconds: Histogram of event processing duration
• vango_event_errors_total: Counter of event errors by path and error type
• vango_patches_sent_total: Counter of patches sent (when RecordPatches is called)
• vango_patch_bytes: Histogram of patch frame sizes by route
• vango_patch_mismatch_total: Counter of patch mismatches by reason
• vango_resource_duration_ms: Histogram of resource durations by resource
• vango_resource_error_total: Counter of resource errors by resource
• vango_action_duration_ms: Histogram of action durations by action
• vango_action_error_total: Counter of action errors by action
• vango_schema_mismatch_total: Counter of schema mismatches by reason
• vango_persist_write_rejected_total: Counter of rejected persisted writes by reason and stable ID
• vango_persist_bytes_total: Counter of persisted bytes by stable ID
• vango_session_persist_bytes: Histogram of persisted bytes per session
• vango_cold_deploy_ack_total: Counter of cold deploy acknowledgments by source
• vango_sessions_active: Gauge of active sessions (when session hooks are used)
• vango_sessions_detached: Gauge of detached sessions
• vango_session_memory_bytes: Histogram of session memory usage
• vango_websocket_errors_total: Counter of WebSocket errors
• vango_reconnects_total: Counter of session reconnections

Example:

app := vango.NewApp(
    vango.WithMiddleware(
        middleware.Prometheus(
            middleware.WithNamespace("myapp"),
        ),
    ),
)

// Expose metrics endpoint
http.Handle("/metrics", promhttp.Handler())

func RecordEviction ¶

func RecordEviction()

RecordEviction records an LRU session eviction.

func RecordPatches ¶

func RecordPatches(count int)

RecordPatches records the number of patches sent. Call this from your server code when patches are sent to clients.

func RecordReconnect ¶

func RecordReconnect()

RecordReconnect records a session reconnection. Call this when a detached session is successfully resumed.

func RecordResume ¶

func RecordResume()

RecordResume records a successful session resume.

func RecordResumeFailed ¶

func RecordResumeFailed(reason string)

RecordResumeFailed records a failed resume attempt.

func RecordSessionCreate ¶

func RecordSessionCreate()

RecordSessionCreate records a new session creation.

func RecordSessionDestroy ¶

func RecordSessionDestroy(memoryBytes int64)

RecordSessionDestroy records a session destruction.

func RecordSessionDetach ¶

func RecordSessionDetach()

RecordSessionDetach records a session becoming detached.

func RecordSessionReattach ¶

func RecordSessionReattach()

RecordSessionReattach records a detached session being reattached.

func RecordWebSocketError ¶

func RecordWebSocketError(errorType string)

RecordWebSocketError records a WebSocket error.

func SpanFromContext ¶

func SpanFromContext(ctx server.Ctx) trace.Span

SpanFromContext retrieves the current trace span from the context. Returns nil if no span is available.

Example:

func MyHandler(ctx server.Ctx) error {
    if span := middleware.SpanFromContext(ctx); span != nil {
        span.SetAttributes(attribute.Int("my.count", 42))
    }
    return nil
}

func TraceContext ¶

func TraceContext(ctx server.Ctx) context.Context

TraceContext returns the trace context from the Ctx for propagation. Use this to propagate trace context to external services.

Example:

func MyHandler(ctx server.Ctx) error {
    traceCtx := middleware.TraceContext(ctx)
    req, _ := http.NewRequestWithContext(traceCtx, "GET", url, nil)
    return nil
}