# apoorvgarg-creator/go-logql architecture

> Architecture diagram of the GitHub repository apoorvgarg-creator/go-logql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/apoorvgarg-creator/go-logql
- Repository: https://github.com/apoorvgarg-creator/go-logql

## Overview

1. **Repository purpose and boundary**
   - This is a **pure Go LogQL query-construction library**, not a Loki client or server. The root package only **builds LogQL strings**; networking, execution, and auth are deliberately out of scope.
   - The architectural boundary is clear: the library produces query text, while callers supply their own HTTP/client layer if they want to send queries to Grafana Loki.

2. **Top-level package structure**
   - The core implementation lives in a small set of root-package files: `logql.go`, `metric.go`, `expr.go`, and `label.go`.
   - That split maps directly to the three main query domains in LogQL:
     - **log queries**
     - **metric/range queries**
     - **binary expressions**
   - `label.go` acts as a shared utility layer for label names, values, quoting, and formatting concerns.

3. **Immutable builder model**
   - The central design pattern is a **fluent immutable builder**.
   - Every method returns a **new value** rather than mutating the existing one, which makes query objects safe to reuse across goroutines and across derived queries.
   - This is the main internal data-flow pattern: base query object → chained transformations → final serialized string.

4. **Log query subsystem**
   - `NewLogQuery()` creates the root log-query builder.
   - `logql.go` represents the stream selector and pipeline stages used to form LogQL log queries:
     - stream selectors such as `Eq`, `Neq`, `Re`, `Nre`
     - line filters such as `LineContains`, `LineMatch`, etc.
     - parsers such as `JSON`, `Logfmt`, `Regexp`, `Pattern`, `Unpack`
     - label filters and pipeline formatting stages such as `LineFormat`, `LabelFormatEntry`, `Drop`, `Keep`, `Decolorize`
     - extraction stage `Unwrap`
   - The output of this subsystem is a complete LogQL log query string like `{job="api"} |= "error"` or `{...} | json | unwrap latency_ms`.

5. **Metric query subsystem**
   - `metric.go` wraps a log query in a **range vector / metric expression**.
   - It provides constructors for Loki range aggregations such as `Rate`, `CountOverTime`, `BytesRate`, `SumOverTime`, `QuantileOverTime`, and others.
   - It also supports metric operators and presentation controls:
     - aggregations: `Sum`, `Avg`, `Min`, `Max`, `Count`, `Stddev`, `Stdvar`
     - selectors: `By`, `Without`
     - modifiers: `Offset`
     - ranking/sorting: `TopK`, `BottomK`, `Sort`, `SortDesc`
   - Architecturally, this layer takes a log query as input and produces metric-form LogQL that can be graphed in Loki/Grafana.

6. **Binary expression subsystem**
   - `expr.go` composes metric expressions using arithmetic, comparison, and logical operators.
   - It supports Loki-style expression combination such as `Add`, `Sub`, `Mul`, `Div`, `CmpGt`, `And`, `Or`, `Unless`, plus boolean modifiers via `Bool()`.
   - This layer is what lets callers build formulas like error-rate percentages or threshold alerts by combining two metric queries.

7. **Shared validation and rendering**
   - Validation is part of the build step rather than construction:
     - at least one stream selector is required
     - label names must be non-empty
     - regexes must compile
     - durations must be positive
     - quantiles must be within `[0, 1]`
     - `topk`/`bottomk` require `k > 0`
   - `Build()` returns `(string, error)` for safe use in application code.
   - `String()` is a convenience layer that panics on invalid input, so it is intended only for already-validated queries.

8. **Data flow through the library**
   - The typical flow is:
     1. create a base log query
     2. chain selector/filter/parser stages
     3. optionally wrap it in a metric/range query
     4. optionally combine metrics with expressions
     5. serialize to a LogQL string
   - This one-way transformation is the core architectural pipeline of the package.

9. **Testing strategy**
   - The repository contains focused unit tests beside each core subsystem: `label_test.go`, `logql_test.go`, `metric_test.go`, `expr_test.go`, plus `example_test.go`.
   - That mirrors the code organization and suggests the important contract is **string correctness and validation behavior** rather than runtime integration.

10. **Examples and integration boundary**
   - The `examples/` directory is a separate Go module that demonstrates end-to-end use against a live Loki stack.
   - It is not part of the library runtime; it is an integration sandbox showing how the generated queries are consumed externally.

11. **Example infrastructure**
   - `examples/docker-compose.yml` brings up three external services:
     - **Loki** as the log backend
     - **Grafana** as the UI
     - **log-simulator** as a log producer
   - `examples/grafana/provisioning/datasources/loki.yml` auto-configures the Loki datasource in Grafana.
   - `examples/loki-config.yml` provides the Loki server config.
   - `examples/log-simulator.sh` continuously emits realistic JSON logs so the sample queries have live data.

12. **How the example app fits**
   - `examples/main.go` demonstrates programmatic query construction and execution against local Loki.
   - The example also highlights the key separation in this repo: the library builds queries, while the example app provides the missing client/execution layer.

13. **External technology footprint**
   - The library itself depends only on the **Go standard library**.
   - The architecture only becomes distributed in the `examples/` sandbox, where Docker Compose, Loki, and Grafana form the runtime environment.

14. **Diagramming takeaway**
   - For an architecture diagram, the core repo should be drawn as a **single pure-Go query builder library** with three internal subsystems:
     - log query builder
     - metric query builder
     - expression builder
   - Surround that with shared validation/formatting utilities and a separate examples/integration environment that connects generated LogQL strings to Loki/Grafana.

Main entry points: [`examples/docker-compose.yml`](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/docker-compose.yml) (Stack setup), [`README.md`](https://github.com/apoorvgarg-creator/go-logql/blob/main/README.md) (API surface), [`metric.go`](https://github.com/apoorvgarg-creator/go-logql/blob/main/metric.go) (Metric queries), [`logql.go`](https://github.com/apoorvgarg-creator/go-logql/blob/main/logql.go) (Log queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core library"]
  node_root_api["API surface<br/>package facade<br/>[README.md]"]
  node_log_builder["Log queries<br/>stream builder<br/>[logql.go]"]
  node_metric_builder["Metric queries<br/>range/vector builder<br/>[metric.go]"]
  node_expr_builder["Binary expr<br/>metric expression<br/>[expr.go]"]
  node_label_utils["Labels<br/>formatting/validation<br/>[label.go]"]
end

subgraph group_examples["Examples sandbox"]
  node_examples_main["Example app<br/>integration demo<br/>[main.go]"]
  node_compose_stack["Stack setup<br/>docker compose<br/>[docker-compose.yml]"]
  node_loki_service[("Loki<br/>log backend<br/>[loki-config.yml]")]
  node_grafana_ui["Grafana<br/>dashboard UI<br/>[loki.yml]"]
  node_log_simulator["Log simulator<br/>log producer<br/>[log-simulator.sh]"]
end

node_root_api -->|"creates"| node_log_builder
node_root_api -->|"creates"| node_metric_builder
node_root_api -->|"creates"| node_expr_builder
node_log_builder -->|"uses"| node_label_utils
node_metric_builder -->|"wraps"| node_log_builder
node_metric_builder -->|"composes"| node_expr_builder
node_expr_builder -->|"combines"| node_metric_builder
node_examples_main -->|"uses"| node_root_api
node_examples_main -->|"runs against"| node_compose_stack
node_compose_stack -->|"starts"| node_loki_service
node_compose_stack -->|"starts"| node_grafana_ui
node_compose_stack -->|"starts"| node_log_simulator
node_grafana_ui -->|"queries"| node_loki_service
node_log_simulator -->|"feeds"| node_loki_service

click node_root_api "https://github.com/apoorvgarg-creator/go-logql/blob/main/README.md"
click node_log_builder "https://github.com/apoorvgarg-creator/go-logql/blob/main/logql.go"
click node_metric_builder "https://github.com/apoorvgarg-creator/go-logql/blob/main/metric.go"
click node_expr_builder "https://github.com/apoorvgarg-creator/go-logql/blob/main/expr.go"
click node_label_utils "https://github.com/apoorvgarg-creator/go-logql/blob/main/label.go"
click node_examples_main "https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/main.go"
click node_compose_stack "https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/docker-compose.yml"
click node_loki_service "https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/loki-config.yml"
click node_grafana_ui "https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/grafana/provisioning/datasources/loki.yml"
click node_log_simulator "https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/log-simulator.sh"

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_root_api,node_log_builder,node_metric_builder,node_expr_builder,node_label_utils toneBlue
class node_examples_main,node_compose_stack,node_loki_service,node_grafana_ui,node_log_simulator toneAmber
```

## Components

### Core library

Pure-Go LogQL query construction and rendering.

- [API surface](https://github.com/apoorvgarg-creator/go-logql/blob/main/README.md): package facade · Root package entry points for constructing and rendering LogQL queries. · `README.md`
- [Log queries](https://github.com/apoorvgarg-creator/go-logql/blob/main/logql.go): stream builder · Builds LogQL stream selectors, line filters, parsers, and pipeline stages. · `logql.go`
- [Metric queries](https://github.com/apoorvgarg-creator/go-logql/blob/main/metric.go): range/vector builder · Wraps log queries in range vectors and metric aggregations, selectors, offsets, and ranking. · `metric.go`
- [Binary expr](https://github.com/apoorvgarg-creator/go-logql/blob/main/expr.go): metric expression · Combines metric expressions with arithmetic, comparison, and logical operators. · `expr.go`
- [Labels](https://github.com/apoorvgarg-creator/go-logql/blob/main/label.go): formatting/validation · Shared label-name, quoting, and formatting logic used across query builders. · `label.go`

### Examples sandbox

Separate integration module that demonstrates generated queries against a live Loki stack.

- [Example app](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/main.go): integration demo · Programmatic query construction and execution against a local Loki instance. · `examples/main.go`
- [Stack setup](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/docker-compose.yml): docker compose · Runs the local Loki, Grafana, and log-simulator services for the example environment. · `examples/docker-compose.yml`
- [Loki](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/loki-config.yml): log backend · External log store and query backend used by the examples. · `examples/loki-config.yml`
- [Grafana](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/grafana/provisioning/datasources/loki.yml): dashboard UI · Visualization layer that reads from Loki via the provisioned datasource. · `examples/grafana/provisioning/datasources/loki.yml`
- [Log simulator](https://github.com/apoorvgarg-creator/go-logql/blob/main/examples/log-simulator.sh): log producer · Shell-based generator that emits sample JSON logs for the demo stack. · `examples/log-simulator.sh`

## Connections

- API surface → Log queries: creates · Root construction begins with log query builders.
- API surface → Metric queries: creates · Root construction also exposes metric query builders.
- API surface → Binary expr: creates · Root construction exposes expression composition.
- Log queries → Labels: uses · Stream selectors and pipeline stages rely on shared label formatting.
- Metric queries → Log queries: wraps · Metric queries take log queries as their input source.
- Metric queries → Binary expr: composes · Metric expressions can be combined into larger formulas.
- Binary expr → Metric queries: combines · Binary expressions operate on metric queries or metric subexpressions.
- Example app → API surface: uses · The example app builds queries with the library API.
- Example app → Stack setup: runs against · The example app targets the local integration stack.
- Stack setup → Loki: starts · Docker Compose brings up Loki as the backend.
- Stack setup → Grafana: starts · Docker Compose brings up Grafana as the UI.
- Stack setup → Log simulator: starts · Docker Compose brings up the sample log producer.
- Grafana → Loki: queries · Grafana reads logs and metrics from Loki through the configured datasource.
- Log simulator → Loki: feeds · Generated logs are ingested by Loki for the demo.