# netflix/spectator architecture

> Architecture diagram of the GitHub repository netflix/spectator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/netflix/spectator
- Repository: https://github.com/netflix/spectator

## Overview

Spectator is a Java library for recording dimensional time-series measurements. Applications create IDs and meters through a Registry, update counters, timers, summaries and gauges, then registry implementations expose or publish measurements. The repository also provides Atlas querying/subscriptions, an HTTP polling endpoint, and optional integrations for JVM/GC, AWS, IPC, logging, Spark and Netflix tagging. The README documents the core instrumentation path; sampled source gives specific evidence for the HTTP endpoint, Atlas subscription refresh and selected integrations, but not every integration’s internal wiring.

Main entry points: [`spectator-api/src/main/java/com/netflix/spectator/api/Registry.java`](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/Registry.java) (Registry API), [`spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/AtlasRegistry.java`](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/AtlasRegistry.java) (Atlas registry), [`spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/SubscriptionManager.java`](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/SubscriptionManager.java) (LWC subscriptions), [`spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/Publisher.java`](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/Publisher.java) (Atlas publisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Instrumentation API"]
  node_registry["Registry API<br/>[Registry.java]"]
  node_ids["IDs and tags<br/>[DefaultId.java]"]
  node_meters["Meters"]
  node_histograms["Histograms"]
  node_patterns["Meter patterns<br/>[PolledMeter.java]"]
end

subgraph group_atlas["Atlas Registry"]
  node_atlasreg["Atlas registry<br/>[AtlasRegistry.java]"]
  node_subscriptions["LWC subscriptions"]
  node_query["Query parsing<br/>[Parser.java]"]
  node_queryindex["Query matching<br/>[QueryIndex.java]"]
  node_publisher["Atlas publisher<br/>[Publisher.java]"]
end

subgraph group_exposure["Metric Exposure"]
  node_httpcontroller["Metrics endpoint"]
end

subgraph group_integrations["Integrations"]
  node_httpclient["IPC HTTP client<br/>[HttpClient.java]"]
  node_ipc["IPC logging<br/>[IpcLogger.java]"]
  node_aws["AWS metrics"]
  node_aws2["AWS SDK v2"]
  node_jvm["JVM metrics<br/>[JmxPoller.java]"]
  node_gc["GC events"]
  node_log4j["Log4j appender"]
  node_spark["Spark reporter"]
  node_placeholders["Placeholder meters"]
  node_netflix["Netflix tagging"]
  node_metrics3["Metrics adapter"]
  node_metrics5["Metrics v5 adapter"]
  node_servlet["Servlet filter"]
end

node_application(("Instrumented app"))
node_atlasservice(("Atlas service"))

node_application -->|"creates meters"| node_registry
node_application -->|"adds dimensions"| node_ids
node_registry -->|"creates IDs"| node_ids
node_application -->|"records values"| node_meters
node_registry -->|"provides meters"| node_meters
node_registry -->|"builds distributions"| node_histograms
node_registry -->|"supports polling"| node_patterns
node_application -->|"selects registry"| node_atlasreg
node_atlasreg -->|"refreshes subscriptions"| node_subscriptions
node_subscriptions -->|"requests expressions"| node_atlasservice
node_atlasreg -->|"parses queries"| node_query
node_atlasreg -->|"matches queries"| node_queryindex
node_atlasreg -->|"publishes measurements"| node_publisher
node_publisher -->|"sends measurements"| node_atlasservice
node_httpcontroller -->|"reads measurements"| node_registry
node_application -->|"requests metrics"| node_httpcontroller
node_httpclient -->|"logs requests"| node_ipc
node_aws -.->|"records latency"| node_registry
node_aws2 -.->|"records metrics"| node_registry
node_jvm -.->|"polls metrics"| node_registry
node_gc -.->|"records events"| node_registry
node_log4j -.->|"records logging"| node_registry
node_spark -.->|"reports metrics"| node_registry
node_placeholders -.->|"provides meters"| node_registry
node_netflix -.->|"adds tags"| node_registry
node_metrics3 -.->|"adapts registry"| node_registry
node_metrics5 -.->|"adapts meters"| node_registry
node_servlet -.->|"integrates requests"| node_ipc

click node_registry "https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/Registry.java"
click node_ids "https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/DefaultId.java"
click node_meters "https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/DefaultRegistry.java"
click node_histograms "https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/histogram/PercentileTimer.java"
click node_patterns "https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/patterns/PolledMeter.java"
click node_atlasreg "https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/AtlasRegistry.java"
click node_subscriptions "https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/SubscriptionManager.java"
click node_query "https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/Parser.java"
click node_queryindex "https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/QueryIndex.java"
click node_publisher "https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/Publisher.java"
click node_httpcontroller "https://github.com/netflix/spectator/blob/main/spectator-web-spring/src/main/java/com/netflix/spectator/controllers/MetricsController.java"
click node_httpclient "https://github.com/netflix/spectator/blob/main/spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/http/HttpClient.java"
click node_ipc "https://github.com/netflix/spectator/blob/main/spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/IpcLogger.java"
click node_aws "https://github.com/netflix/spectator/blob/main/spectator-ext-aws/src/main/java/com/netflix/spectator/aws/SpectatorServiceMetricCollector.java"
click node_aws2 "https://github.com/netflix/spectator/blob/main/spectator-ext-aws2/src/main/java/com/netflix/spectator/aws2/SpectatorExecutionInterceptor.java"
click node_jvm "https://github.com/netflix/spectator/blob/main/spectator-ext-jvm/src/main/java/com/netflix/spectator/jvm/JmxPoller.java"
click node_gc "https://github.com/netflix/spectator/blob/main/spectator-ext-gc/src/main/java/com/netflix/spectator/gc/GcEventListener.java"
click node_log4j "https://github.com/netflix/spectator/blob/main/spectator-ext-log4j2/src/main/java/com/netflix/spectator/log4j/SpectatorAppender.java"
click node_spark "https://github.com/netflix/spectator/blob/main/spectator-ext-spark/src/main/java/com/netflix/spectator/spark/SpectatorReporter.java"
click node_placeholders "https://github.com/netflix/spectator/blob/main/spectator-ext-placeholders/src/main/java/com/netflix/spectator/placeholders/DefaultPlaceholderFactory.java"
click node_netflix "https://github.com/netflix/spectator/blob/main/spectator-nflx-tagging/src/main/java/com/netflix/spectator/nflx/tagging/NetflixTagging.java"
click node_metrics3 "https://github.com/netflix/spectator/blob/main/spectator-reg-metrics3/src/main/java/com/netflix/spectator/metrics3/MetricsRegistry.java"
click node_metrics5 "https://github.com/netflix/spectator/blob/main/spectator-reg-metrics5/src/main/java/com/netflix/spectator/metrics5/MetricsCounter.java"
click node_servlet "https://github.com/netflix/spectator/blob/main/spectator-ext-ipcservlet/src/main/java/com/netflix/spectator/ipcservlet/IpcServletFilter.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_registry,node_ids,node_meters,node_histograms,node_patterns toneBlue
class node_atlasreg,node_subscriptions,node_query,node_queryindex,node_publisher toneAmber
class node_httpcontroller toneMint
class node_httpclient,node_ipc,node_aws,node_aws2,node_jvm,node_gc,node_log4j,node_spark,node_placeholders,node_netflix,node_metrics3,node_metrics5,node_servlet toneRose
class node_application,node_atlasservice toneIndigo
```

## Components

### Instrumentation API

- [Registry API](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/Registry.java): `spectator-api/src/main/java/com/netflix/spectator/api/Registry.java`
- [IDs and tags](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/DefaultId.java): `spectator-api/src/main/java/com/netflix/spectator/api/DefaultId.java`
- [Meters](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/DefaultRegistry.java): `spectator-api/src/main/java/com/netflix/spectator/api/DefaultRegistry.java`
- [Histograms](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/histogram/PercentileTimer.java): `spectator-api/src/main/java/com/netflix/spectator/api/histogram/PercentileTimer.java`
- [Meter patterns](https://github.com/netflix/spectator/blob/main/spectator-api/src/main/java/com/netflix/spectator/api/patterns/PolledMeter.java): `spectator-api/src/main/java/com/netflix/spectator/api/patterns/PolledMeter.java`

### Atlas Registry

- [Atlas registry](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/AtlasRegistry.java): `spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/AtlasRegistry.java`
- [LWC subscriptions](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/SubscriptionManager.java): `spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/SubscriptionManager.java`
- [Query parsing](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/Parser.java): `spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/Parser.java`
- [Query matching](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/QueryIndex.java): `spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/impl/QueryIndex.java`
- [Atlas publisher](https://github.com/netflix/spectator/blob/main/spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/Publisher.java): `spectator-reg-atlas/src/main/java/com/netflix/spectator/atlas/Publisher.java`

### Metric Exposure

- [Metrics endpoint](https://github.com/netflix/spectator/blob/main/spectator-web-spring/src/main/java/com/netflix/spectator/controllers/MetricsController.java): `spectator-web-spring/src/main/java/com/netflix/spectator/controllers/MetricsController.java`

### Integrations

- [IPC HTTP client](https://github.com/netflix/spectator/blob/main/spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/http/HttpClient.java): `spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/http/HttpClient.java`
- [IPC logging](https://github.com/netflix/spectator/blob/main/spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/IpcLogger.java): `spectator-ext-ipc/src/main/java/com/netflix/spectator/ipc/IpcLogger.java`
- [AWS metrics](https://github.com/netflix/spectator/blob/main/spectator-ext-aws/src/main/java/com/netflix/spectator/aws/SpectatorServiceMetricCollector.java): `spectator-ext-aws/src/main/java/com/netflix/spectator/aws/SpectatorServiceMetricCollector.java`
- [AWS SDK v2](https://github.com/netflix/spectator/blob/main/spectator-ext-aws2/src/main/java/com/netflix/spectator/aws2/SpectatorExecutionInterceptor.java): `spectator-ext-aws2/src/main/java/com/netflix/spectator/aws2/SpectatorExecutionInterceptor.java`
- [JVM metrics](https://github.com/netflix/spectator/blob/main/spectator-ext-jvm/src/main/java/com/netflix/spectator/jvm/JmxPoller.java): `spectator-ext-jvm/src/main/java/com/netflix/spectator/jvm/JmxPoller.java`
- [GC events](https://github.com/netflix/spectator/blob/main/spectator-ext-gc/src/main/java/com/netflix/spectator/gc/GcEventListener.java): `spectator-ext-gc/src/main/java/com/netflix/spectator/gc/GcEventListener.java`
- [Log4j appender](https://github.com/netflix/spectator/blob/main/spectator-ext-log4j2/src/main/java/com/netflix/spectator/log4j/SpectatorAppender.java): `spectator-ext-log4j2/src/main/java/com/netflix/spectator/log4j/SpectatorAppender.java`
- [Spark reporter](https://github.com/netflix/spectator/blob/main/spectator-ext-spark/src/main/java/com/netflix/spectator/spark/SpectatorReporter.java): `spectator-ext-spark/src/main/java/com/netflix/spectator/spark/SpectatorReporter.java`
- [Placeholder meters](https://github.com/netflix/spectator/blob/main/spectator-ext-placeholders/src/main/java/com/netflix/spectator/placeholders/DefaultPlaceholderFactory.java): `spectator-ext-placeholders/src/main/java/com/netflix/spectator/placeholders/DefaultPlaceholderFactory.java`
- [Netflix tagging](https://github.com/netflix/spectator/blob/main/spectator-nflx-tagging/src/main/java/com/netflix/spectator/nflx/tagging/NetflixTagging.java): `spectator-nflx-tagging/src/main/java/com/netflix/spectator/nflx/tagging/NetflixTagging.java`
- [Metrics adapter](https://github.com/netflix/spectator/blob/main/spectator-reg-metrics3/src/main/java/com/netflix/spectator/metrics3/MetricsRegistry.java): `spectator-reg-metrics3/src/main/java/com/netflix/spectator/metrics3/MetricsRegistry.java`
- [Metrics v5 adapter](https://github.com/netflix/spectator/blob/main/spectator-reg-metrics5/src/main/java/com/netflix/spectator/metrics5/MetricsCounter.java): `spectator-reg-metrics5/src/main/java/com/netflix/spectator/metrics5/MetricsCounter.java`
- [Servlet filter](https://github.com/netflix/spectator/blob/main/spectator-ext-ipcservlet/src/main/java/com/netflix/spectator/ipcservlet/IpcServletFilter.java): `spectator-ext-ipcservlet/src/main/java/com/netflix/spectator/ipcservlet/IpcServletFilter.java`

### Other components

- **Instrumented app**
- **Atlas service**

## Connections

- Instrumented app → Registry API: creates meters
- Instrumented app → IDs and tags: adds dimensions
- Registry API → IDs and tags: creates IDs
- Instrumented app → Meters: records values
- Registry API → Meters: provides meters
- Registry API → Histograms: builds distributions
- Registry API → Meter patterns: supports polling
- Instrumented app → Atlas registry: selects registry
- Atlas registry → LWC subscriptions: refreshes subscriptions
- LWC subscriptions → Atlas service: requests expressions
- Atlas registry → Query parsing: parses queries
- Atlas registry → Query matching: matches queries
- Atlas registry → Atlas publisher: publishes measurements
- Atlas publisher → Atlas service: sends measurements
- Metrics endpoint → Registry API: reads measurements
- Instrumented app → Metrics endpoint: requests metrics
- IPC HTTP client → IPC logging: logs requests
- AWS metrics → Registry API: records latency
- AWS SDK v2 → Registry API: records metrics
- JVM metrics → Registry API: polls metrics
- GC events → Registry API: records events
- Log4j appender → Registry API: records logging
- Spark reporter → Registry API: reports metrics
- Placeholder meters → Registry API: provides meters
- Netflix tagging → Registry API: adds tags
- Metrics adapter → Registry API: adapts registry
- Metrics v5 adapter → Registry API: adapts meters
- Servlet filter → IPC logging: integrates requests