# grafana/dskit architecture

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

- Interactive diagram: https://gitdiagram.com/grafana/dskit
- Repository: https://github.com/grafana/dskit

## Overview

##### Project type and purpose
- This is not a standalone application but a Go library (“Grafana Dskit”) providing reusable, production-grade building blocks for distributed services (retry/backoff, caching, KV stores, middleware, service lifecycle, etc.).
- It’s consumed by Grafana’s upstream services (Mimir, Loki, Tempo, Pyroscope) to avoid re-implementing common patterns.

##### File structure
- Each top-level folder (backoff, cache, kv, middleware, ring, services, tracing, etc.) is a self-contained Go package implementing one abstract API or utility.
- Certain folders cluster around functionality:
- Core abstractions: backoff, cache, kv, ring, services, middleware, grpcutil, httpgrpc
- Implementations: cache/{memcached,redis}, kv/{consul,etcd,memberlist}, grpcencoding/snappy
- Cross-cutting concerns: tracing, log, metrics, instrument, spanlogger, spanprofiler
- Utilities: concurrency, cancellation, limiter, multierror, runutil, clusterutil, netutil, signals, runtimeconfig, promregistry
- Service/framework support: server, servicediscovery, modules, user, ballast, gate, loser
- Build and CI: Makefile, Go modules, GitHub workflows, linting, test scripts.

##### README
- Emphasizes the library’s pieces: backoff, cache API, hedging, kv API, RPC middleware, services model.
- Mentions production usage at scale in Grafana’s core products.

a. Main components (group into logical clusters):
1) Clients (Grafana services)
2) Dskit Core Abstractions (Retry/Backoff, Cache API, KV API, Ring API, Services Model, Middleware Interface)
3) Implementations (Memcached, Redis, Consul, Etcd, Memberlist, gRPC, HTTP/gRPC, Snappy)
4) Cross-cutting Utilities (Tracing, Logging, Metrics, Instrumentation, Cancellation, Concurrency, Rate Limiting)
5) Service Hosting (Server, Service Discovery, Modules, Lifecycle, Runtime Config)
6) Auxiliary Utilities (Multierror, Netutil, Signals, Runutil, Clusterutil)

b. Relationships and data flow
- Core Abstractions → Implementations (e.g. Cache API → Redis/Memcached clients; KV API → Etcd/Consul/Memberlist).
- Middleware sits between transport layers (gRPC/HTTP) and application, leveraging Logging, Metrics, Tracing.
- Retry/Backoff, Hedging, Rate Limiter, Cancellation wrap outbound calls.
- Ring & Service Discovery coordinate with Memberlist/Consul under the hood.
- Services Model orchestrates startup/shutdown of Server, Modules, RuntimeConfig.

c. Architectural patterns and design principles
- Modular package-per-concern: each package defines an interface + zero or more pluggable implementations.
- Dependency Injection via interface abstractions (clients pass in e.g. BackoffStrategy, CacheClient, KVClient).
- Cross-cutting concerns isolated in middleware layers and utility packages.
- Composition over inheritance: building pipelines of middleware, retries, hedging by composing small functions.
- Clear separation of API (interface) vs. implementation.

d. Key technologies/frameworks
- Go modules, standard Go tooling.
- gRPC and HTTP/gRPC (protobufs, codegen).
- Memcached, Redis clients.
- Etcd, Consul, Memberlist for service discovery/kv.
- OpenTelemetry/Opentracing instrumentation.
- Prometheus registry for metrics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients (Grafana Services)" 
        Clients["Grafana Services"]:::external
    end

    %% Core Abstractions
    subgraph "Core Abstractions" 
        RetryBackoff["Retry/Backoff"]:::core
        CacheAPI["Cache API"]:::core
        KVAPI["KV API"]:::core
        RingAPI["Ring API"]:::core
        ServicesModel["Services Model"]:::core
        MiddlewareInterface["Middleware Interface"]:::core
        GRPCUtils["gRPC Utilities"]:::core
        HTTPGRPC["HTTP/gRPC Transport"]:::core
    end

    %% Implementations
    subgraph "Implementations" 
        Memcached["Memcached Client"]:::impl
        Redis["Redis Client"]:::impl
        Consul["Consul KV"]:::impl
        Etcd["Etcd KV"]:::impl
        Memberlist["Memberlist KV"]:::impl
        RingPool["Ring Client Pool"]:::impl
        BasicLifecycler["Basic Lifecycler"]:::impl
        GRPCLogging["gRPC Logging Middleware"]:::impl
        HTTPTimeout["HTTP Timeout Middleware"]:::impl
        Snappy["Snappy Encoding"]:::impl
    end

    %% Cross-Cutting Concerns
    subgraph "Cross-Cutting Concerns" 
        Tracing["Tracing"]:::cross
        Logging["Logging"]:::cross
        Metrics["Metrics"]:::cross
        Instrumentation["Instrumentation"]:::cross
        SpanLogger["Span Logger"]:::cross
        SpanProfiler["Span Profiler"]:::cross
    end

    %% Utilities
    subgraph "Utilities" 
        Concurrency["Concurrency Utilities"]:::util
        Cancellation["Cancellation Utilities"]:::util
        RateLimiter["Rate Limiter"]:::util
        Multierror["Multi-error Utilities"]:::util
        Runutil["Run Utilities"]:::util
        Clusterutil["Cluster Utilities"]:::util
        Netutil["Network Utilities"]:::util
        Signals["Signal Handling Utilities"]:::util
    end

    %% Service Hosting
    subgraph "Service Hosting" 
        RuntimeConfig["Runtime Configuration"]:::host
        PromRegistry["Prometheus Registry"]:::host
        ServerHosting["Server Hosting"]:::host
        ServiceDiscovery["Service Discovery"]:::host
        Modules["Module Framework"]:::host
        UserContext["User Context Utilities"]:::host
        Ballast["Ballast Utility"]:::host
        Gate["Gate Utility"]:::host
        Loser["Loser Utility"]:::host
    end

    %% Connections: Clients to Core
    Clients -->|uses| RetryBackoff
    Clients -->|uses| CacheAPI
    Clients -->|uses| KVAPI
    Clients -->|uses| RingAPI
    Clients -->|uses| ServicesModel
    Clients -->|invokes| MiddlewareInterface
    Clients -->|calls| GRPCUtils
    Clients -->|calls| HTTPGRPC

    %% Core to Implementations
    CacheAPI -->|implements| Memcached
    CacheAPI -->|implements| Redis
    KVAPI -->|implements| Consul
    KVAPI -->|implements| Etcd
    KVAPI -->|implements| Memberlist
    RingAPI -->|uses| RingPool
    RingAPI -->|uses| BasicLifecycler
    MiddlewareInterface -->|implements| GRPCLogging
    MiddlewareInterface -->|implements| HTTPTimeout
    HTTPGRPC -->|encodes| Snappy

    %% Cross-cutting usage
    RetryBackoff -->|wraps| Tracing
    MiddlewareInterface -->|uses| Logging
    MiddlewareInterface -->|collects| Metrics
    MiddlewareInterface -->|adds| Instrumentation
    MiddlewareInterface -->|logs| SpanLogger
    MiddlewareInterface -->|profiles| SpanProfiler

    %% Utilities usage
    RetryBackoff -->|uses| Concurrency
    RetryBackoff -->|honors| Cancellation
    RetryBackoff -->|applies| RateLimiter
    ServicesModel -->|aggregates| Multierror
    ServicesModel -->|manages| Runutil
    ServicesModel -->|integrates| Clusterutil
    ServicesModel -->|configures| Netutil
    ServicesModel -->|handles| Signals

    %% Service Hosting relationships
    ServicesModel -->|orchestrates| ServerHosting
    ServicesModel -->|provides| ServiceDiscovery
    ServicesModel -->|loads| Modules
    ServicesModel -->|reads| RuntimeConfig
    Metrics -->|registers| PromRegistry
    ServiceDiscovery -->|dns| ServiceDiscovery
    HTTPGRPC -->|hosts| ServerHosting

    %% Click Events
    click RetryBackoff "https://github.com/grafana/dskit/blob/main/backoff/backoff.go"
    click CacheAPI "https://github.com/grafana/dskit/blob/main/cache/cache.go"
    click Memcached "https://github.com/grafana/dskit/blob/main/cache/memcached_client.go"
    click Redis "https://github.com/grafana/dskit/blob/main/cache/redis_client.go"
    click KVAPI "https://github.com/grafana/dskit/blob/main/kv/client.go"
    click Consul "https://github.com/grafana/dskit/blob/main/kv/consul/client.go"
    click Etcd "https://github.com/grafana/dskit/blob/main/kv/etcd/etcd.go"
    click Memberlist "https://github.com/grafana/dskit/blob/main/kv/memberlist/memberlist_client.go"
    click RingAPI "https://github.com/grafana/dskit/blob/main/ring/ring.go"
    click RingPool "https://github.com/grafana/dskit/blob/main/ring/client/pool.go"
    click BasicLifecycler "https://github.com/grafana/dskit/blob/main/ring/basic_lifecycler.go"
    click ServicesModel "https://github.com/grafana/dskit/blob/main/services/service.go"
    click ServicesModel "https://github.com/grafana/dskit/blob/main/services/manager.go"
    click ServicesModel "https://github.com/grafana/dskit/blob/main/services/basic_service.go"
    click MiddlewareInterface "https://github.com/grafana/dskit/blob/main/middleware/middleware.go"
    click GRPCLogging "https://github.com/grafana/dskit/blob/main/middleware/grpc_logging.go"
    click HTTPTimeout "https://github.com/grafana/dskit/blob/main/middleware/http_timeout.go"
    click GRPCUtils "https://github.com/grafana/dskit/blob/main/grpcutil/dns_resolver.go"
    click GRPCUtils "https://github.com/grafana/dskit/blob/main/grpcutil/metadata.go"
    click GRPCUtils "https://github.com/grafana/dskit/blob/main/grpcutil/health_check.go"
    click HTTPGRPC "https://github.com/grafana/dskit/blob/main/httpgrpc/httpgrpc.go"
    click ServerHosting "https://github.com/grafana/dskit/blob/main/httpgrpc/server/server.go"
    click Snappy "https://github.com/grafana/dskit/blob/main/grpcencoding/snappy/snappy.go"
    click Tracing "https://github.com/grafana/dskit/blob/main/tracing/tracing.go"
    click Logging "https://github.com/grafana/dskit/blob/main/log/global.go"
    click Metrics "https://github.com/grafana/dskit/blob/main/metrics/helpers.go"
    click Instrumentation "https://github.com/grafana/dskit/blob/main/instrument/instrument.go"
    click SpanLogger "https://github.com/grafana/dskit/blob/main/spanlogger/spanlogger.go"
    click SpanProfiler "https://github.com/grafana/dskit/blob/main/spanprofiler/spanprofiler.go"
    click Concurrency "https://github.com/grafana/dskit/blob/main/concurrency/runner.go"
    click Cancellation "https://github.com/grafana/dskit/blob/main/cancellation/error.go"
    click RateLimiter "https://github.com/grafana/dskit/blob/main/limiter/rate_limiter.go"
    click Multierror "https://github.com/grafana/dskit/blob/main/multierror/multierror.go"
    click Runutil "https://github.com/grafana/dskit/blob/main/runutil/runutil.go"
    click Clusterutil "https://github.com/grafana/dskit/blob/main/clusterutil/clusterutil.go"
    click Netutil "https://github.com/grafana/dskit/blob/main/netutil/netutil.go"
    click Signals "https://github.com/grafana/dskit/blob/main/signals/signals.go"
    click RuntimeConfig "https://github.com/grafana/dskit/blob/main/runtimeconfig/manager.go"
    click PromRegistry "https://github.com/grafana/dskit/blob/main/promregistry/registry.go"
    click ServerHosting "https://github.com/grafana/dskit/blob/main/server/server.go"
    click ServiceDiscovery "https://github.com/grafana/dskit/blob/main/servicediscovery/dns.go"
    click Modules "https://github.com/grafana/dskit/blob/main/modules/modules.go"
    click UserContext "https://github.com/grafana/dskit/blob/main/user/http.go"
    click Ballast "https://github.com/grafana/dskit/blob/main/ballast/ballast.go"
    click Gate "https://github.com/grafana/dskit/blob/main/gate/gate.go"
    click Loser "https://github.com/grafana/dskit/blob/main/loser/loser.go"

    %% Styles
    classDef external fill:#dddddd,stroke:#888888,color:#000000
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000000
    classDef impl fill:#d4edda,stroke:#28a745,color:#000000
    classDef cross fill:#ffe5b4,stroke:#ff9900,color:#000000
    classDef util fill:#f8d7da,stroke:#dc3545,color:#000000
    classDef host fill:#e2e3e5,stroke:#6c757d,color:#000000
```
