Monitoring Cirata Symphony

Cirata Symphony provides built-in observability through health endpoints, extension status tracking, and application logs. The Observability extension provides centralised collection of OpenTelemetry metrics, logs, and traces from both the platform and all connected extensions.

Overview

Capability	Description	Details
Health check	Unauthenticated ping endpoint for load balancers	Status
Extension status	Real-time heartbeat-based health tracking	Status
Platform telemetry	OTLP metrics, logs, and traces from the platform core	Below
Browser telemetry	Automatic tracing of UI interactions, HTTP and NATS requests	Below
Observability extension	Centralised collection, OTLP export, and querying	Below

Platform Telemetry

Symphony emits metrics, logs, and traces via OTLP, collected by the Observability extension over NATS. The platform publishes telemetry on the cirata.symphony.{metrics,logs,traces} subjects.

Platform Metrics

Metric	Type	Description
http.requests.total	Counter	Total HTTP requests
http.responses.2xx	Counter	Successful responses
http.responses.4xx	Counter	Client error responses
http.responses.5xx	Counter	Server error responses
nats.service.requests.total	Counter	Extension service proxy requests
extensions.registered.total	Counter	Extension registrations
auth.attempts.total	Counter	Authentication attempts
auth.failures.total	Counter	Authentication failures
licensing.checks.total	Counter	License enforcement checks
licensing.enforcements.blocked	Counter	Requests blocked by enforcement

Platform Traces

Every HTTP request and NATS service call generates a trace span with attributes including method, route, status code, and duration. Traces propagate through the HTTP middleware into extension service calls, producing connected spans: HTTP request → platform → extension. The browser UI propagates W3C trace context on every HTTP and NATS request, so platform spans appear as children of browser-initiated traces when viewed in the collector.

Browser Telemetry

The Symphony UI automatically generates trace spans for all user interactions. These browser-side spans appear in the collector under service name ui, correlated with backend spans by shared trace IDs.

What is Traced

Signal	Span Name Pattern	Attributes
Page navigation	page /path	navigation.path, duration_ms
HTTP request	HTTP GET /api/v1/...	http.method, http.url, http.status_code
NATS request	nats.request cirata.services...	nats.subject

All HTTP and NATS requests include W3C traceparent headers, enabling the platform to create child spans that link back to the browser's trace. No configuration is required—browser telemetry is enabled by default.

Trace Flow

A typical user interaction produces a trace spanning browser, platform, and extension:

page /dashboard              (ui)
├─ HTTP GET /api/v1/roles    (ui → symphony)
├─ nats.request licensing    (ui → symphony)
│  └─ licensing handler      (symphony)
└─ nats.request shares       (ui → symphony)
   └─ shares handler         (symphony → extension)

Export

Browser spans are exported as JSON to the platform's cirata.symphony.traces NATS endpoint every 2 seconds, where they are converted to OTLP protobuf and collected by the Observability Extension alongside platform and extension spans.

Observability Extension

The Observability extension provides centralised metrics aggregation for deployments where multiple extensions produce OpenTelemetry metrics. It is not included in the base Symphony installation and must be deployed separately.

What It Does

The extension automatically discovers extensions and the platform that publish OpenTelemetry (OTLP) telemetry, collects their data on a 30-second interval, and forwards it to configured OTLP backends (Prometheus, InfluxDB, Grafana, etc.). This gives operators a unified view of metrics, logs, and traces from every instrumented component without configuring individual scrape targets.

Capabilities

• Service discovery—automatically finds extensions and the platform publishing telemetry on NATS
• OTLP export—pushes collected metrics, logs, and traces to any OTLP-compatible backend
• Metric querying—query scalar metrics (gauges, sums) and histogram metrics by time range, service attributes, and metric tags
• Namespace and service browsing—explore available metrics by service namespace, name, instance, and telemetry SDK
• CLI integration—all query operations are exposed as dynamic CLI commands via the cirata observability command group

Supported Metric Types

Type	Description
Gauge	Point-in-time values (e.g. memory usage, queue depth)
Sum	Monotonic or non-monotonic counters (e.g. requests processed)
Histogram	Distribution data with explicit bucket boundaries

Example CLI Usage

When the Observability extension is connected, its operations appear as dynamic CLI commands:

# List all service namespaces with recorded metrics
cirata observability find_all_namespaces

# List services in a namespace
cirata observability find_services_by_namespace default

# Discover available metrics
cirata observability find_metrics

# Query scalar metric data
cirata observability query_scalar_metrics jvm.memory.used \
  2026-03-14T00:00:00Z 2026-03-14T12:00:00Z

Deploying the Extension

The Observability extension is a Java (Spring Boot) application that connects to Symphony using an API key token. It stores metrics locally in an embedded DuckDB database and requires no additional infrastructure. See the extension's own documentation for deployment instructions.

Troubleshooting

Missing Extension Metrics

Check that the extension is connected (cirata extension list) and has registered its observability endpoints. Deploy the Observability extension to automatically discover and collect metrics from all connected extensions and the platform.

High Memory Usage

Monitor JetStream memory usage. If memory is near the limit, increase jetstream.max_mem in nats.config and restart Symphony.

See Also

• Status—Health checks, extension status, and logs
• CLI Reference—CLI commands