{
  "generator": {
    "name": "Symvanta",
    "url": "https://symvanta.com"
  },
  "page": {
    "url": "https://symvanta.com/architecture/prometheus",
    "title": "Prometheus Architecture: How It Actually Works",
    "description": "How the Prometheus codebase is structured: module map, load-bearing symbols, and dependency structure, generated by Symvanta.",
    "datePublished": "2026-08-08",
    "dateModified": "2026-08-08"
  },
  "repository": {
    "name": "prometheus/prometheus",
    "url": "https://github.com/prometheus/prometheus",
    "commit": "e75af38",
    "license": "Apache-2.0"
  },
  "graph": {
    "modules": 53,
    "dependencyCycles": 8,
    "modularityQ": 0.71,
    "largestCycleFiles": 16,
    "mutuallyRecursiveGroups": 10
  },
  "summaryMarkdown": "Prometheus is a single Go binary that scrapes targets, writes samples into a\nlocal time series database, and answers PromQL queries against it. Symvanta's\ngraph of the repo at `e75af38` detects 53 functional modules at modularity\nQ=0.71, and the weight sits almost entirely in storage: the three largest\nclusters are built from `tsdb`, `labels`, `chunkenc`, and `wlog`, with the\nscrape loop, service discovery, and remote write arranged around them.\n\nThe clearest structural signal is where the cycles are. All 8 dependency cycles\nlive in the web UI (`web/ui/react-app`, `web/ui/mantine-ui`, and the\ncodemirror-promql module). The Go packages that make up the server have none.",
  "subsystems": [
    {
      "name": "tsdb chunks and label matching",
      "descriptionMarkdown": "Chunk access (`tsdb.memChunk.len`, `chunkenc.NewNopIterator`) sits with label\nhandling (`labels.NewFastRegexMatcher`, `strutil.SanitizeLabelName`) and\npostings iteration inside one 855-symbol cluster, because a query touches all\nthree on its way to a sample."
    },
    {
      "name": "tsdb head and WAL",
      "descriptionMarkdown": "The mutable half of the database: the recent window held in memory and the log\nthat lets it survive a restart. 628 symbols covering `tsdb.open`,\n`tsdb.NewHead`, `tsdb.DefaultHeadOptions`, and the write-ahead log\n(`wlog.NewSize`, `wlog.WL.Log`)."
    },
    {
      "name": "Storage append and iterate",
      "descriptionMarkdown": "Everything that writes samples passes through the `Appender` and `Iterator`\ninterfaces collected here, including the newer `AppenderV2`. The two heaviest\nedges on the map run between this 812-symbol cluster and the head and WAL\ncluster: 262 calls out, 319 back."
    },
    {
      "name": "HTTP API v1",
      "descriptionMarkdown": "Where the query engine meets the network. `apiFuncResult`, `apiError`, `Query`,\nand `SearchResult` read from the storage clusters and shape what goes back over\nthe wire, 486 symbols in all."
    },
    {
      "name": "Config loading and file handling",
      "descriptionMarkdown": "`config.LoadFile`, `fileutil.Flock`, tombstone writes, decode buffers: 517\nsymbols of plumbing that every other cluster calls. Its PageRank hub is the bare\n`Error` method, which is what a cluster in that position looks like in Go."
    },
    {
      "name": "Scrape loop and appendables",
      "descriptionMarkdown": "`scrape.foreachAppendable` and the appendable test doubles, 311 symbols. The\ningest path shows up in two edge weights: 56 calls into the discovery registry,\n44 into the append interfaces."
    }
  ],
  "startReading": {
    "symbols": [
      {
        "name": "tsdb.memChunk.len"
      },
      {
        "name": "tsdbutil.DirLocker.Lock"
      },
      {
        "name": "stats.Timer.Duration"
      },
      {
        "name": "Appender"
      },
      {
        "name": "encoding.Encbuf.PutUvarint"
      },
      {
        "name": "labels.NewMatcher"
      },
      {
        "name": "scrape.foreachAppendable"
      },
      {
        "name": "chunkenc.bstream.bytes"
      }
    ],
    "endpoints": [
      {
        "method": "GET",
        "path": "/graph"
      },
      {
        "method": "GET",
        "path": "/federate"
      },
      {
        "method": "GET",
        "path": "/consoles/*filepath"
      },
      {
        "method": "GET",
        "path": "/user/*filepath"
      },
      {
        "method": "GET",
        "path": "/-/healthy"
      },
      {
        "method": "HEAD",
        "path": "/-/healthy"
      },
      {
        "method": "GET",
        "path": "/-/ready"
      },
      {
        "method": "HEAD",
        "path": "/-/ready"
      },
      {
        "method": "GET",
        "path": "/-/quit"
      },
      {
        "method": "GET",
        "path": "/-/reload"
      }
    ]
  },
  "requestFlow": [
    {
      "position": 1,
      "symbol": "tsdb.Open (tsdb/db.go:910)",
      "sourceUrl": null,
      "markdown": "`tsdb.Open (tsdb/db.go:910)`"
    },
    {
      "position": 2,
      "symbol": "tsdb.open (tsdb/db.go:992)",
      "sourceUrl": null,
      "markdown": "`tsdb.open (tsdb/db.go:992)`"
    },
    {
      "position": 3,
      "symbol": "tsdbutil.NewDirLocker",
      "sourceUrl": null,
      "markdown": "`tsdbutil.NewDirLocker`"
    },
    {
      "position": 4,
      "symbol": "tsdbutil.DirLocker.Lock",
      "sourceUrl": null,
      "markdown": "`tsdbutil.DirLocker.Lock`"
    },
    {
      "position": 5,
      "symbol": "tsdbutil.RemoveTmpDirs",
      "sourceUrl": null,
      "markdown": "`tsdbutil.RemoveTmpDirs`"
    },
    {
      "position": 6,
      "symbol": "wlog.DeleteTempCheckpoints",
      "sourceUrl": null,
      "markdown": "`wlog.DeleteTempCheckpoints`"
    },
    {
      "position": 7,
      "symbol": "wlog.NewSize",
      "sourceUrl": null,
      "markdown": "`wlog.NewSize`"
    },
    {
      "position": 8,
      "symbol": "wlog.WL.Repair",
      "sourceUrl": null,
      "markdown": "`wlog.WL.Repair`"
    },
    {
      "position": 9,
      "symbol": "chunkenc.NewPool",
      "sourceUrl": null,
      "markdown": "`chunkenc.NewPool`"
    },
    {
      "position": 10,
      "symbol": "tsdb.NewLeveledCompactorWithOptions",
      "sourceUrl": null,
      "markdown": "`tsdb.NewLeveledCompactorWithOptions`"
    },
    {
      "position": 11,
      "symbol": "tsdb.NewHead",
      "sourceUrl": null,
      "markdown": "`tsdb.NewHead`"
    },
    {
      "position": 12,
      "symbol": "tsdb.Head.Init",
      "sourceUrl": null,
      "markdown": "`tsdb.Head.Init`"
    }
  ],
  "diagrams": [
    {
      "url": "https://symvanta.com/architecture/prometheus/module-map.svg",
      "encodingFormat": "image/svg+xml"
    }
  ]
}