Observability Capability¶

The Observability capability exports traces, metrics, and logs to external monitoring systems.

Contract¶

public interface ObservabilityContract extends BaseProviderContract {
    void exportTraces(List<TraceSpan> spans);
    void exportMetrics(List<MetricsEnvelope> metrics);
    void exportLogs(List<StructuredLogEntry> logs);
    HealthStatus healthStatus();
    void configureAlerts(List<AlertRule> rules);
}

Observability Stack¶

PatternOps uses industry standards:

Signal	Standard	Format
Traces	OpenTelemetry	OTLP
Metrics	OpenTelemetry	MetricsEnvelope (canonical)
Logs	Structured JSON	StructuredLogEntry
Correlation	W3C Trace Context	trace-id across all signals

Metrics Envelope¶

The canonical metric format used across all providers:

record MetricsEnvelope(
    String tenancy,
    String namespace,
    String dataset,
    String pipeline,
    String runId,
    ExecutionMode executionMode,
    String provider,
    String stage,
    String metricName,      // max 128 characters
    double metricValue,
    CanonicalUnit metricUnit,
    long timestamp,         // UTC milliseconds
    Map<String, String> dimensions  // max 20 entries
) { }

Canonical Units¶

Unit	Description
`count`	Discrete count
`bytes`	Data size
`milliseconds`	Duration (ms)
`seconds`	Duration (s)
`percent`	Percentage (0-100)
`records_per_second`	Throughput
`bytes_per_second`	Bandwidth
`ratio`	Ratio (0.0-1.0)
`events_per_second`	Event throughput

Structured Log Entry¶

record StructuredLogEntry(
    String timestamp,       // ISO-8601 UTC
    LogLevel level,         // debug, info, warn, error
    String service,
    String tenancy,
    String namespace,
    String pipeline,
    String runId,
    String correlationId,   // W3C Trace Context trace-id
    String message
) { }

W3C Trace Context Correlation¶

A single correlationId (W3C trace-id) links:

Traces across services
Metrics for a specific execution
Log entries for debugging
Lineage events for data flow

Example Providers¶

Provider	Signals
OpenTelemetry Collector	Traces, Metrics, Logs
Prometheus	Metrics
Grafana Loki	Logs
Datadog	Traces, Metrics, Logs
Splunk	Logs, Metrics
AWS CloudWatch	Metrics, Logs
ELK Stack	Logs

Dashboard Generation¶

The Documentation Engine generates monitoring dashboards for:

Grafana (JSON model, Prometheus + Loki sources)
Kibana (NDJSON export)
Splunk (XML dashboard)
Datadog (JSON dashboard)
CloudWatch (JSON dashboard)