# max-bytes/metrics-receiver architecture

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

- Interactive diagram: https://gitdiagram.com/max-bytes/metrics-receiver
- Repository: https://github.com/max-bytes/metrics-receiver

## Overview

metrics-receiver is a Go HTTP service that accepts Influx line-protocol writes and forwards processed metrics to configured TimescaleDB and InfluxDB outputs. The main runtime workflow parses and groups points, applies per-output filtering and measurement rules, optionally enriches tags from a cached Omnikeeper query, then dispatches writes. It also exposes health and enrichment-cache endpoints and can emit internal metrics. The README documents the status and cache APIs; source excerpts establish the write and enrichment paths, while some handler and orchestration lines are omitted.

Main entry points: [`cmd/metrics-receiver/main.go`](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go) (HTTP Service), [`pkg/general/processMeasurementPoints.go`](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/general/processMeasurementPoints.go) (Filter and Prepare), [`pkg/enrichments/omnikeeper.go`](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/enrichments/omnikeeper.go) (Enrichment Fetch), [`pkg/timescale/write.go`](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/timescale/write.go) (Timescale Writer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_service["HTTP Service<br/>[main.go]"]
  node_parser["Line Parser"]
  node_health["Health Check<br/>[main.go]"]
  node_cacheapi["Cache Info API<br/>[main.go]"]
  node_internalmetrics["Internal Metrics<br/>[main.go]"]
end

subgraph group_processing["Metric Processing"]
  node_config["Runtime Config<br/>[config.go]"]
  node_grouping["Measurement Grouping"]
  node_prepare["Filter and Prepare"]
end

subgraph group_enrichment["Enrichment"]
  node_enrichment["Enrichment Fetch<br/>[omnikeeper.go]"]
  node_cache[("Enrichment Cache<br/>[omnikeeper.go]")]
end

subgraph group_outputs["Storage Outputs"]
  node_dispatch["Output Dispatch<br/>[main.go]"]
  node_timescale["Timescale Writer<br/>[write.go]"]
  node_timescaledb[("TimescaleDB")]
  node_influxwriter["Influx Writer<br/>[write.go]"]
  node_influxdb[("InfluxDB")]
end

node_sender(("Metric Sender"))
node_omnikeeper["Omnikeeper API"]

node_sender -->|"sends writes"| node_service
node_service -->|"parses body"| node_parser
node_service -->|"groups points"| node_grouping
node_service -->|"loads config"| node_config
node_service -->|"prepares outputs"| node_prepare
node_prepare -->|"reads rules"| node_config
node_prepare -->|"looks up tags"| node_cache
node_service -->|"dispatches writes"| node_dispatch
node_dispatch -->|"writes points"| node_timescale
node_dispatch -->|"writes points"| node_influxwriter
node_timescale -->|"inserts rows"| node_timescaledb
node_influxwriter -->|"writes points"| node_influxdb
node_service -->|"starts refresh"| node_enrichment
node_enrichment -->|"queries traits"| node_omnikeeper
node_enrichment -->|"updates cache"| node_cache
node_service -->|"serves check"| node_health
node_service -->|"serves cache info"| node_cacheapi
node_cacheapi -->|"reads cache"| node_cache
node_service -->|"collects counters"| node_internalmetrics
node_internalmetrics -->|"flushes metrics"| node_dispatch

click node_service "https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go"
click node_parser "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/influx/InfluxLineProtocolParser.go"
click node_config "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/config/config.go"
click node_grouping "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/general/splitPointsByMeasurement.go"
click node_prepare "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/general/processMeasurementPoints.go"
click node_enrichment "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/enrichments/omnikeeper.go"
click node_cache "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/enrichments/omnikeeper.go"
click node_health "https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go"
click node_cacheapi "https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go"
click node_internalmetrics "https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go"
click node_dispatch "https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go"
click node_timescale "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/timescale/write.go"
click node_influxwriter "https://github.com/max-bytes/metrics-receiver/blob/master/pkg/influx/write.go"

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_service,node_parser,node_health,node_cacheapi,node_internalmetrics toneBlue
class node_config,node_grouping,node_prepare toneAmber
class node_enrichment,node_cache,node_omnikeeper toneMint
class node_dispatch,node_timescale,node_timescaledb,node_influxwriter,node_influxdb toneRose
class node_sender toneIndigo
```

## Components

### Ingestion

- [HTTP Service](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go): `cmd/metrics-receiver/main.go`
- [Line Parser](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/influx/InfluxLineProtocolParser.go): `pkg/influx/InfluxLineProtocolParser.go`
- [Health Check](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go): `cmd/metrics-receiver/main.go`
- [Cache Info API](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go): `cmd/metrics-receiver/main.go`
- [Internal Metrics](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go): `cmd/metrics-receiver/main.go`

### Metric Processing

- [Runtime Config](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/config/config.go): `pkg/config/config.go`
- [Measurement Grouping](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/general/splitPointsByMeasurement.go): `pkg/general/splitPointsByMeasurement.go`
- [Filter and Prepare](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/general/processMeasurementPoints.go): `pkg/general/processMeasurementPoints.go`

### Enrichment

- [Enrichment Fetch](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/enrichments/omnikeeper.go): `pkg/enrichments/omnikeeper.go`
- [Enrichment Cache](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/enrichments/omnikeeper.go): `pkg/enrichments/omnikeeper.go`

### Storage Outputs

- [Output Dispatch](https://github.com/max-bytes/metrics-receiver/blob/master/cmd/metrics-receiver/main.go): `cmd/metrics-receiver/main.go`
- [Timescale Writer](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/timescale/write.go): `pkg/timescale/write.go`
- **TimescaleDB**
- [Influx Writer](https://github.com/max-bytes/metrics-receiver/blob/master/pkg/influx/write.go): `pkg/influx/write.go`
- **InfluxDB**

### Other components

- **Metric Sender**
- **Omnikeeper API**

## Connections

- Metric Sender → HTTP Service: sends writes
- HTTP Service → Line Parser: parses body
- HTTP Service → Measurement Grouping: groups points
- HTTP Service → Runtime Config: loads config
- HTTP Service → Filter and Prepare: prepares outputs
- Filter and Prepare → Runtime Config: reads rules
- Filter and Prepare → Enrichment Cache: looks up tags
- HTTP Service → Output Dispatch: dispatches writes
- Output Dispatch → Timescale Writer: writes points
- Output Dispatch → Influx Writer: writes points
- Timescale Writer → TimescaleDB: inserts rows
- Influx Writer → InfluxDB: writes points
- HTTP Service → Enrichment Fetch: starts refresh
- Enrichment Fetch → Omnikeeper API: queries traits
- Enrichment Fetch → Enrichment Cache: updates cache
- HTTP Service → Health Check: serves check
- HTTP Service → Cache Info API: serves cache info
- Cache Info API → Enrichment Cache: reads cache
- HTTP Service → Internal Metrics: collects counters
- Internal Metrics → Output Dispatch: flushes metrics