Observability

Observability

Atmosphere 4.0 includes built-in observability: Micrometer metrics, OpenTelemetry tracing, structured logging via SLF4J MDC, and a backpressure interceptor for overload protection. All components live in atmosphere-runtime — no additional dependencies required (beyond Micrometer/OpenTelemetry themselves).

Micrometer Metrics

Setup

MeterRegistry registry = new PrometheusMeterRegistry(PrometheusConfig.DEFAULT);
AtmosphereMetrics metrics = AtmosphereMetrics.install(framework, registry);

With rooms:

metrics.instrumentRoomManager(roomManager);

Available Metrics

Metric	Type	Description
atmosphere.connections.active	Gauge	Currently connected clients
atmosphere.connections.total	Counter	Total connections since startup
atmosphere.connections.disconnects	Counter	Total disconnections
atmosphere.messages.broadcast	Counter	Messages broadcast
atmosphere.messages.delivered	Counter	Messages delivered to clients
atmosphere.broadcast.timer	Timer	Broadcast latency
atmosphere.broadcasters.active	Gauge	Active Broadcasters
atmosphere.rooms.active	Gauge	Active Rooms
atmosphere.rooms.members	Gauge	Members per room (tagged by room name)
atmosphere.rooms.messages	Counter	Messages per room (tagged by room name)
atmosphere.cache.size	Gauge	BroadcasterCache entries
atmosphere.cache.hits	Counter	Cache hits
atmosphere.cache.misses	Counter	Cache misses
atmosphere.cache.evictions	Counter	Cache evictions
atmosphere.backpressure.drops	Counter	Messages dropped by backpressure
atmosphere.backpressure.disconnects	Counter	Clients disconnected by backpressure

Spring Boot Actuator

When using the Spring Boot starter with spring-boot-starter-actuator, metrics are auto-exposed:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: health,metrics
  endpoint:
    health:
      show-details: always

Metrics are available at /actuator/metrics/atmosphere.connections.active, etc.

Grafana Dashboard

A ready-to-import Grafana dashboard is available at samples/shared-resources/grafana/atmosphere-dashboard.json. It includes panels for connections, message rates, broadcast latency (p50/p95/p99), room members, cache performance, and backpressure.

OpenTelemetry Tracing

Setup

framework.interceptor(new AtmosphereTracing(GlobalOpenTelemetry.get()));

Or with a specific Tracer:

Tracer tracer = openTelemetry.getTracer("atmosphere");
framework.interceptor(new AtmosphereTracing(tracer));

Span Attributes

Every request creates a span with these attributes:

Attribute	Description
atmosphere.resource.uuid	Unique connection identifier
atmosphere.transport	Transport type (websocket, sse, etc.)
atmosphere.action	Request action
atmosphere.broadcaster	Broadcaster ID
atmosphere.room	Room name (if applicable)

Room operations get dedicated spans via startRoomSpan(operation, roomName, uuid).

Structured Logging — MDCInterceptor

MDCInterceptor populates SLF4J MDC keys on every request so log lines include Atmosphere context:

framework.interceptor(new MDCInterceptor());

MDC Keys

Key	Value
atmosphere.uuid	Unique resource identifier
atmosphere.transport	Transport type
atmosphere.broadcaster	Broadcaster ID

Logback Pattern Example

%d{HH:mm:ss.SSS} [%thread] %-5level [uuid=%X{atmosphere.uuid} transport=%X{atmosphere.transport}] %logger{36} - %msg%n

MDC keys are automatically included as top-level fields in JSON layouts (logstash-logback-encoder, logback-contrib).

Backpressure

The BackpressureInterceptor protects against slow consumers by limiting the number of pending messages per client:

framework.interceptor(new BackpressureInterceptor());

Configuration

Parameter	Default	Description
org.atmosphere.backpressure.highWaterMark	1000	Max pending messages per client
org.atmosphere.backpressure.policy	drop-oldest	drop-oldest, drop-newest, or disconnect

Policies

Policy	Behavior
drop-oldest	Drops the oldest pending message to make room (default)
drop-newest	Drops the incoming message
disconnect	Disconnects the slow client

Monitoring

BackpressureInterceptor bp = new BackpressureInterceptor();
bp.pendingCount(uuid);     // Pending messages for a client
bp.totalDrops();           // Total messages dropped
bp.totalDisconnects();     // Total clients disconnected

Drop and disconnect counts are also exposed via Micrometer as atmosphere.backpressure.drops and atmosphere.backpressure.disconnects.

Cache Configuration

The UUIDBroadcasterCache (installed by default with @ManagedService) supports tuning:

Parameter	Default	Description
org.atmosphere.cache.UUIDBroadcasterCache.maxPerClient	1000	Max cached messages per client
org.atmosphere.cache.UUIDBroadcasterCache.messageTTL	300	Per-message TTL in seconds
org.atmosphere.cache.UUIDBroadcasterCache.maxTotal	100000	Global cache size limit

See Also

• Understanding AtmosphereInterceptor — interceptor pipeline
• Understanding Broadcaster — the pub/sub bus
• Clustering with Kafka and Redis — multi-node deployments