# open5gs/prometheus-client-c architecture

> Architecture diagram of the GitHub repository open5gs/prometheus-client-c, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/open5gs/prometheus-client-c
- Repository: https://github.com/open5gs/prometheus-client-c

## Overview

##### Project Type & Purpose
- Type: An open-source C library for instrumenting applications with Prometheus metrics.
- Purpose:
– libprom: core API for creating counters, gauges, histograms, collector registries, etc.
– libpromhttp: thin HTTP handler (built on libmicrohttpd) to expose metrics over HTTP for scraping by Prometheus.
– promtest & example: test harnesses and usage examples.
– auto / Docker / Make: development automation (build, test, smoke tests).

##### High-Level Components
A. Application Code (example/, user binaries)
B. Core Library (libprom)
- Metric types (counter, gauge, histogram)
- Collector registry, process/OS collectors (fds, limits, stat)
- Internal data structures (linked list, map, string builder)
- pthreads for concurrency
C. HTTP Layer (libpromhttp)
- Wraps libmicrohttpd to expose /metrics endpoint
- Pulls data from libprom registry, formats for Prometheus
D. External Services & Dependencies
- Prometheus Server (scrapes HTTP endpoint)
- libmicrohttpd (HTTP server library)
- POSIX (pthreads, procfs for process stats)
E. Development Tooling
- auto/ scripts, Makefile, Dockerfile – orchestrate build, test, docs
- CI pipeline (.github/workflows/ci.yaml)
- Doxygen docs (docs/*)
- promtest – unit/integration tests

##### Relationships & Data Flow
1. Application invokes libprom API to register metrics and update values at runtime.
2. libprom stores metrics in in-memory registry.
3. libpromhttp registers an HTTP handler with libmicrohttpd; on HTTP GET /metrics:
a. libpromhttp queries libprom registry for current metric values.
b. libpromhttp formats metrics in Prometheus text exposition format.
4. Prometheus server periodically issues HTTP GET requests to the libpromhttp endpoint, collects metrics.
5. Development pipeline leverages Docker/Make to: compile both libraries, run unit tests (prom/test, promtest), run smoke tests (example), and generate Doxygen docs.

##### Architectural Patterns & Principles
- Layered modular design:
– Core (“business logic”) layer (libprom)
– Adapter layer (libpromhttp + libmicrohttpd)
– Application layer (example, user code)
- Separation of concerns: metric creation vs. HTTP exposure vs. storage vs. build tooling.
- Dependency inversion: libprom has zero third-party dependencies; libpromhttp depends on libmicrohttpd.

##### Critical Elements to Capture
- Separation between libprom and libpromhttp.
- The registry as central data store.
- libmicrohttpd as external HTTP dependency.
- Prometheus as external scraper.
- Build automation and CI orchestrating compilation, testing, and docs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "Application Layer"
        direction TB
        App["Example Application"]:::app
    end

    %% Core Library Layer
    subgraph "Core Library (libprom)"
        direction TB
        CoreAPI["libprom API\n(counter, gauge, histogram)"]:::core
        Registry["Metric Registry\n(linked list, map)"]:::core
    end

    %% HTTP Adapter Layer
    subgraph "HTTP Layer (libpromhttp)"
        direction TB
        HTTPHandler["libpromhttp\n(/metrics handler)"]:::http
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PromServer["Prometheus Server"]:::ext
        MHD["libmicrohttpd"]:::ext
        POSIX["POSIX (pthreads, procfs)"]:::ext
    end

    %% Development Tooling
    subgraph "Development Tooling"
        direction TB
        Build["Makefile / Docker / auto scripts"]:::tool
        CI["CI Pipeline"]:::tool
        Docs["Doxygen Docs"]:::tool
        Tests["Unit/Integration Tests"]:::tool
    end

    %% Connections
    App -->|"prom_counter_increment() etc."| CoreAPI
    CoreAPI -->|"stores metrics"| Registry
    HTTPHandler -->|"queries Registry"| Registry
    HTTPHandler -->|"registers with"| MHD
    PromServer -->|"HTTP GET /metrics"| HTTPHandler
    CoreAPI --- POSIX
    HTTPHandler --- POSIX
    Build --> CoreAPI
    Build --> HTTPHandler
    Build --> Tests
    Build --> Docs
    CI --> Build
    CI --> Tests

    %% Click Events
    click CoreAPI "https://github.com/open5gs/prometheus-client-c/tree/main/prom/include/"
    click Registry "https://github.com/open5gs/prometheus-client-c/tree/main/prom/src/"
    click HTTPHandler "https://github.com/open5gs/prometheus-client-c/blob/main/promhttp/src/promhttp.c"
    click HTTPHandler "https://github.com/open5gs/prometheus-client-c/blob/main/promhttp/include/promhttp.h"
    click App "https://github.com/open5gs/prometheus-client-c/blob/main/example/main.c"
    click App "https://github.com/open5gs/prometheus-client-c/blob/main/example/foo.c"
    click App "https://github.com/open5gs/prometheus-client-c/blob/main/example/bar.c"
    click App "https://github.com/open5gs/prometheus-client-c/tree/main/example/Makefile"
    click Tests "https://github.com/open5gs/prometheus-client-c/blob/main/promtest/CMakeLists.txt"
    click Tests "https://github.com/open5gs/prometheus-client-c/tree/main/promtest/test/"
    click Tests "https://github.com/open5gs/prometheus-client-c/tree/main/prom/test/"
    click Tests "https://github.com/open5gs/prometheus-client-c/tree/main/prom/test/fixtures/"
    click Build "https://github.com/open5gs/prometheus-client-c/blob/main/auto/autolib.sh"
    click Build "https://github.com/open5gs/prometheus-client-c/blob/main/auto/build.sh"
    click Build "https://github.com/open5gs/prometheus-client-c/tree/main/auto/cmd/"
    click Build "https://github.com/open5gs/prometheus-client-c/tree/main/docker/Makefile"
    click Build "https://github.com/open5gs/prometheus-client-c/tree/main/Makefile"
    click CI "https://github.com/open5gs/prometheus-client-c/blob/main/.github/workflows/ci.yaml"
    click Docs "https://github.com/open5gs/prometheus-client-c/blob/main/docs/index.html"
    click Docs "https://github.com/open5gs/prometheus-client-c/tree/main/docs/"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef http fill:#DFF7DD,stroke:#22863A,color:#22863A;
    classDef ext fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef tool fill:#FFF5D1,stroke:#D29922,color:#D29922;
    classDef app fill:#FFE4E1,stroke:#D73A49,color:#D73A49;
```
