@primafuture/telemetry-stack 0.1.0

package/stack/configs/config.alloy

@@ -0,0 +1,74 @@
+// Main Alloy pipeline for application telemetry.
+// It receives OTLP traces, metrics, and logs from apps and routes them to the stack.
+
+// Copy selected log attributes into resource attributes so Loki can index them as labels.
+otelcol.processor.transform "loki_labels" {
+  log_statements {
+    context = "log"
+    statements = [
+      `set(resource.attributes["log_type"], attributes["log_type"]) where attributes["log_type"] != nil`,
+      `set(resource.attributes["log.file.path"], attributes["log.file.path"]) where attributes["log.file.path"] != nil`,
+    ]
+  }
+  output {
+    logs = [otelcol.processor.batch.pipeline.input]
+  }
+}
+
+// Public OTLP receiver exposed by the alloy service.
+// Applications send OTLP gRPC to port 4317 or OTLP HTTP to port 4318.
+otelcol.receiver.otlp "otlp_receiver" {
+  grpc {
+    endpoint = "0.0.0.0:4317"
+  }
+  http {
+    endpoint = "0.0.0.0:4318"
+  }
+
+  output {
+    traces = [otelcol.processor.batch.pipeline.input]
+    metrics = [otelcol.processor.batch.pipeline.input]
+    // Logs pass through the label transform first, then continue into the shared batch processor.
+    logs = [otelcol.processor.transform.loki_labels.input]
+  }
+}
+
+// Batch processor reduces exporter overhead and fans telemetry out by signal type.
+otelcol.processor.batch "pipeline" {
+  output {
+    traces = [otelcol.exporter.otlp.tempo.input]
+    metrics = [otelcol.exporter.prometheus.prometheus.input]
+    logs = [otelcol.exporter.otlphttp.loki_otlp.input]
+  }
+}
+
+// Send traces to Tempo through OTLP gRPC.
+otelcol.exporter.otlp "tempo" {
+  client {
+    endpoint = sys.env("ALLOY_OTLP_UPSTREAM")
+    tls {
+      insecure = true
+    }
+  }
+}
+
+// Convert OpenTelemetry metrics to Prometheus remote_write samples.
+otelcol.exporter.prometheus "prometheus" {
+  forward_to = [prometheus.remote_write.default.receiver]
+}
+
+// Store metrics in Prometheus first; Prometheus then forwards them to Mimir.
+prometheus.remote_write "default" {
+  endpoint {
+    url = sys.env("ALLOY_PROM_REMOTE_WRITE_URL")
+    protobuf_message = "io.prometheus.write.v2.Request"
+    send_native_histograms = true
+  }
+}
+
+// Send logs to Loki through its OTLP HTTP endpoint, for example http://loki:3100/otlp.
+otelcol.exporter.otlphttp "loki_otlp" {
+  client {
+    endpoint = sys.env("ALLOY_LOKI_OTLP_ENDPOINT")
+  }
+}

package/stack/configs/grafana-datasources.yaml

@@ -0,0 +1,105 @@
+# Grafana datasource provisioning for the local telemetry stack.
+# Grafana loads this file at startup and creates ready-to-use data sources.
+apiVersion: 1
+
+datasources:
+# Prometheus is used for short-term metrics and for trace exemplars.
+- name: Prometheus
+  type: prometheus
+  uid: prometheus
+  access: proxy
+  orgId: 1
+  url: http://prometheus:9090
+  basicAuth: false
+  isDefault: false
+  version: 1
+  editable: true
+  jsonData:
+    httpMethod: GET
+    exemplarTraceIdDestinations:
+    - datasourceUid: tempo-streaming-disabled
+      name: trace_id
+# Mimir exposes the same Prometheus query API for metrics stored in object storage.
+- name: Mimir
+  type: prometheus
+  uid: mimir
+  access: proxy
+  orgId: 1
+  url: http://mimir:9009/prometheus
+  basicAuth: false
+  isDefault: false
+  version: 1
+  editable: true
+  jsonData:
+    httpMethod: GET
+# Loki is used for logs. Derived fields turn trace_id and span_id labels into Tempo links.
+- name: Loki
+  type: loki
+  uid: loki
+  access: proxy
+  orgId: 1
+  url: http://loki:3100
+  basicAuth: false
+  isDefault: false
+  version: 1
+  editable: true
+  jsonData:
+    httpMethod: GET
+    derivedFields:
+    - datasourceUid: tempo-streaming-disabled
+      matcherRegex: trace_id
+      matcherType: label
+      name: Traceid
+      url: "$${__value.raw}"
+      urlDisplayLabel: "$${__value.raw} (Tempo)"
+    - datasourceUid: tempo-streaming-disabled
+      matcherRegex: span_id
+      matcherType: label
+      name: SpanId
+      url: '{span:id = "$${__value.raw}"}'
+      urlDisplayLabel: "$${__value.raw} (Tempo)"
+# This Tempo datasource enables streaming features and is the default trace datasource.
+- name: Tempo (yes streaming)
+  type: tempo
+  access: proxy
+  orgId: 1
+  url: http://tempo:3200
+  basicAuth: false
+  isDefault: true
+  version: 1
+  editable: true
+  apiVersion: 1
+  uid: tempo-streaming-enabled
+  jsonData:
+    httpMethod: GET
+    serviceMap:
+      datasourceUid: prometheus
+    streamingEnabled:
+      search: true
+      metrics: true
+# This Tempo datasource keeps streaming disabled for links that need stable TraceQL behavior.
+- name: Tempo (no streaming)
+  type: tempo
+  access: proxy
+  orgId: 1
+  url: http://tempo:3200
+  basicAuth: false
+  isDefault: false
+  version: 1
+  editable: true
+  apiVersion: 1
+  uid: tempo-streaming-disabled
+  jsonData:
+    httpMethod: GET
+    serviceMap:
+      datasourceUid: prometheus
+    tracesToLogsV2:
+      customQuery: false
+      datasourceUid: loki
+      filterBySpanID: true
+      filterByTraceID: true
+      spanEndTimeShift: 10s
+      spanStartTimeShift: "-10s"
+      tags:
+      - key: service.name
+        value: service_name

package/stack/configs/prometheus.yaml

@@ -0,0 +1,23 @@
+# Local Prometheus configuration for development and demos.
+# Prometheus receives remote_write data from Alloy, scrapes local stack targets, and forwards metrics to Mimir.
+
+# Scrape every 15 seconds so demo graphs update quickly.
+global:
+  scrape_interval:     15s
+  evaluation_interval: 15s
+
+# Forward all collected metrics to Mimir for long-term metric storage.
+remote_write:
+  - url: http://mimir:9009/api/v1/push
+    send_native_histograms: true
+
+# Scrape built-in stack targets.
+scrape_configs:
+  - job_name: 'prometheus'
+    static_configs:
+      - targets: [ 'localhost:9090' ]
+  # Tempo exposes internal metrics on its HTTP port.
+  - job_name: 'tempo'
+    static_configs:
+      - targets:
+          - 'tempo:3200'

package/stack/configs/redpanda-console.yaml

@@ -0,0 +1,5 @@
+# Redpanda Console configuration for the local stack.
+# The console connects to the Redpanda service over the Docker network.
+kafka:
+  brokers:
+    - redpanda:9092

package/stack/docker-compose.yaml

@@ -0,0 +1,146 @@
+# Telemetry stack used by the npm CLI.
+# TELEMETRY_DATA_DIR must point to the host directory where runtime data is stored.
+# Host ports can be overridden with environment variables, for example GRAFANA_PORT=3300.
+services:
+  # Pre-creates writable data directories before services with different container UIDs start.
+  init-data:
+    image: library/busybox:latest@sha256:b3255e7dfbcd10cb367af0d409747d511aeb66dfac98cf30e97e87e4207dd76f
+    volumes:
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}:/data
+    command: sh -c "mkdir -p /data/tempo /data/minio /data/redpanda /data/loki /data/mimir /data/prometheus /data/grafana && chmod 0777 /data/tempo /data/minio /data/redpanda /data/loki /data/mimir /data/prometheus /data/grafana"
+
+  # Tempo stores traces and accepts OTLP trace data from Alloy.
+  tempo:
+    image: grafana/tempo:latest@sha256:f3eed6cfd68a2e9eef773f3e2eb0f56cef27cf00a34dd60c7e62c90ef07d02f8
+    depends_on:
+      init-data:
+        condition: service_completed_successfully
+      redpanda:
+        condition: service_started
+    command: "-target=all -config.file=/etc/tempo.yaml"
+    restart: always
+    volumes:
+      - ${TELEMETRY_GENERATED_CONFIG_DIR:?Set TELEMETRY_GENERATED_CONFIG_DIR}/tempo.yaml:/etc/tempo.yaml:ro
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/tempo:/var/tempo
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${TEMPO_PORT:-3200}:3200"
+
+  # MinIO provides local S3-compatible object storage for Tempo, Loki, and Mimir.
+  minio:
+    image: minio/minio:latest@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e
+    volumes:
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/minio:/data
+    environment:
+      - MINIO_ROOT_USER=${TELEMETRY_MINIO_ACCESS_KEY:?Set TELEMETRY_MINIO_ACCESS_KEY}
+      - MINIO_ROOT_PASSWORD=${TELEMETRY_MINIO_SECRET_KEY:?Set TELEMETRY_MINIO_SECRET_KEY}
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${MINIO_CONSOLE_PORT:-9001}:9001"
+    entrypoint:
+      - sh
+      - -euc
+      - mkdir -p /data/tempo /data/loki /data/mimir && minio server /data --console-address ':9001'
+
+  # Mimir stores long-term metrics and receives remote_write data from Prometheus.
+  mimir:
+    image: grafana/mimir:latest@sha256:df4b7a5fefba96c19fa3e0b3d3ecceed32892ef49ae893ce37492cfe4f299645
+    command: -target=all -config.file=/etc/mimir.yaml
+    volumes:
+      - ${TELEMETRY_GENERATED_CONFIG_DIR:?Set TELEMETRY_GENERATED_CONFIG_DIR}/mimir.yaml:/etc/mimir.yaml:ro
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/mimir:/var/mimir
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${MIMIR_PORT:-9009}:9009"
+    depends_on:
+      init-data:
+        condition: service_completed_successfully
+      minio:
+        condition: service_started
+
+  # Redpanda is the Kafka-compatible broker used by Tempo ingestion.
+  redpanda:
+    image: redpandadata/redpanda:latest@sha256:a6340e8d52455996b6fbe34df219305cb934eddceab2da2ce8e1ef32bbe04703
+    volumes:
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/redpanda:/var/lib/redpanda/data
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${REDPANDA_PORT:-9092}:9092"
+    command: >
+      redpanda start --overprovisioned
+      --mode=dev-container
+      --kafka-addr=PLAINTEXT://0.0.0.0:9092
+      --advertise-kafka-addr=PLAINTEXT://redpanda:9092
+
+  # Redpanda Console is the browser UI for inspecting the local Redpanda broker.
+  redpanda-console:
+    image: docker.redpanda.com/redpandadata/console:v3.5.0@sha256:b2cbdd93dee412142f95a61488118f33b8e31ea576bfb3ce625fbaffbdf0803a
+    environment:
+      - CONFIG_FILEPATH=/etc/redpanda/redpanda-console-config.yaml
+    volumes:
+      - ./configs/redpanda-console.yaml:/etc/redpanda/redpanda-console-config.yaml
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${REDPANDA_CONSOLE_PORT:-8080}:8080"
+    depends_on:
+      - redpanda
+
+  # Alloy is the main OpenTelemetry gateway for app traces, metrics, and logs.
+  alloy:
+    image: grafana/alloy:latest@sha256:8abcd0d97a97099cabb34be8dcfc448fca6c35931ae9291aaf74056105dedcca
+    volumes:
+      - ./configs/config.alloy:/etc/alloy/config.alloy
+    command:
+      - run
+      - /etc/alloy/config.alloy
+      - --storage.path=/var/lib/alloy/data
+      - --server.http.listen-addr=0.0.0.0:12345
+      - --stability.level=experimental
+    environment:
+      - ALLOY_OTLP_UPSTREAM=tempo:4317
+      - ALLOY_PROM_REMOTE_WRITE_URL=http://prometheus:9090/api/v1/write
+      - ALLOY_LOKI_OTLP_ENDPOINT=http://loki:3100/otlp
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${ALLOY_PORT:-12345}:12345"
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${OTLP_GRPC_PORT:-4317}:4317"
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${OTLP_HTTP_PORT:-4318}:4318"
+    depends_on:
+      - tempo
+      - prometheus
+      - loki
+
+  # Loki stores logs and exposes them to Grafana through the Loki datasource.
+  loki:
+    image: grafana/loki:latest@sha256:3c8fd3570dd9219951a60d3f919c7f31923d10baee578b77bc26c4a0b32d092d
+    command: -config.file=/etc/loki/config.yaml
+    volumes:
+      - ${TELEMETRY_GENERATED_CONFIG_DIR:?Set TELEMETRY_GENERATED_CONFIG_DIR}/loki.yaml:/etc/loki/config.yaml:ro
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/loki:/loki
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${LOKI_PORT:-3100}:3100"
+
+  # Prometheus receives metrics from Alloy, scrapes local jobs, and forwards to Mimir.
+  prometheus:
+    image: prom/prometheus:latest@sha256:4a61322ac1103a0e3aea2a61ef1718422a48fa046441f299d71e660a3bc71ae9
+    command:
+      - --config.file=/etc/prometheus.yaml
+      - --storage.tsdb.retention.time=7d
+      - --web.enable-remote-write-receiver
+      - --enable-feature=exemplar-storage
+      - --enable-feature=native-histograms
+    volumes:
+      - ./configs/prometheus.yaml:/etc/prometheus.yaml
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/prometheus:/prometheus
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${PROMETHEUS_PORT:-9090}:9090"
+
+  # Grafana is the browser UI with datasources provisioned from stack/configs.
+  grafana:
+    image: grafana/grafana:latest@sha256:b0ae311af06228bcfd4a620504b653db80f5b91e94dc3dc2a5b7dab202bcde20
+    volumes:
+      - ./configs/grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml
+      - ${TELEMETRY_DATA_DIR:?Set TELEMETRY_DATA_DIR}/grafana:/var/lib/grafana
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=${GRAFANA_ANONYMOUS_ENABLED:-true}
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=${GRAFANA_ANONYMOUS_ORG_ROLE:-Admin}
+      - GF_AUTH_DISABLE_LOGIN_FORM=${GRAFANA_DISABLE_LOGIN_FORM:-true}
+      - GF_SECURITY_ADMIN_USER=${GRAFANA_ADMIN_USER:-admin}
+      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD:-admin}
+      - GF_FEATURE_TOGGLES_ENABLE=traceqlEditor metricsSummary
+    ports:
+      - "${TELEMETRY_BIND_ADDRESS:-0.0.0.0}:${GRAFANA_PORT:-3000}:3000"

package/stack/templates/loki.yaml

@@ -0,0 +1,63 @@
+# Generated Loki configuration.
+# This file is rendered from the package template; edit telemetry-stack.env instead.
+auth_enabled: false
+
+server:
+  http_listen_port: 3100
+
+# Single-process ring suitable only for this local Docker Compose stack.
+common:
+  ring:
+    instance_addr: 127.0.0.1
+    kvstore:
+      store: inmemory
+  replication_factor: 1
+  path_prefix: /loki
+
+# TSDB schema backed by the local MinIO S3-compatible storage service.
+schema_config:
+  configs:
+    - from: 2024-04-01
+      store: tsdb
+      object_store: s3
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h
+
+# Store Loki chunks and indexes in the local MinIO bucket named loki.
+storage_config:
+  tsdb_shipper:
+    active_index_directory: /loki/index
+    cache_location: /loki/index_cache
+    cache_ttl: 24h
+  aws:
+    endpoint: http://minio:9000
+    bucketnames: loki
+    access_key_id: "{{TELEMETRY_MINIO_ACCESS_KEY}}"
+    secret_access_key: "{{TELEMETRY_MINIO_SECRET_KEY}}"
+    s3forcepathstyle: true
+    insecure: true
+    region: us-east-1
+
+# Compactor enforces retention and deletes old objects from MinIO.
+compactor:
+  working_directory: /loki/retention
+  compaction_interval: 10m
+  retention_enabled: true
+  retention_delete_delay: 2h
+  retention_delete_worker_count: 150
+  delete_request_store: s3
+
+# Keep demo logs for 7 days.
+limits_config:
+  retention_period: 168h
+
+# OTLP logs arrive with resource attributes. This list chooses which attributes
+# Loki indexes as labels; dots are converted to underscores in Loki/Grafana.
+distributor:
+  otlp_config:
+    default_resource_attributes_as_index_labels:
+      - service.name
+      - log_type
+      - log.file.path

package/stack/templates/mimir.yaml

@@ -0,0 +1,52 @@
+# Generated Mimir configuration.
+# This file is rendered from the package template; edit telemetry-stack.env instead.
+
+multitenancy_enabled: false
+
+# Mimir exposes its HTTP API on the internal Docker network.
+server:
+  http_listen_port: 9009
+
+# Store metric blocks in the local MinIO bucket named mimir.
+common:
+  storage:
+    backend: s3
+    s3:
+      endpoint: minio:9000
+      access_key_id: "{{TELEMETRY_MINIO_ACCESS_KEY}}"
+      secret_access_key: "{{TELEMETRY_MINIO_SECRET_KEY}}"
+      insecure: true
+      bucket_name: mimir
+
+# Blocks storage requires a prefix when using a common object storage bucket.
+blocks_storage:
+  storage_prefix: blocks
+  tsdb:
+    dir: /var/mimir/tsdb
+  bucket_store:
+    sync_dir: /var/mimir/tsdb-sync
+
+# Run a single local ingester with an in-memory memberlist ring.
+ingester:
+  ring:
+    kvstore:
+      store: memberlist
+    replication_factor: 1
+
+# Enable native histograms and keep demo metrics for 7 days.
+limits:
+  native_histograms_ingestion_enabled: true
+  compactor_blocks_retention_period: 168h
+
+# Compact old metric blocks and enforce retention.
+compactor:
+  data_dir: /var/mimir/compactor
+  sharding_ring:
+    kvstore:
+      store: memberlist
+
+# Store gateway serves blocks from object storage back to queriers.
+store_gateway:
+  sharding_ring:
+    kvstore:
+      store: memberlist

package/stack/templates/tempo.yaml

@@ -0,0 +1,99 @@
+# Generated Tempo configuration.
+# This file is rendered from the package template; edit telemetry-stack.env instead.
+
+partition_ring_live_store: true
+stream_over_http_enabled: true
+
+# Tempo exposes its HTTP API on port 3200 inside the Docker network.
+server:
+  http_listen_port: 3200
+  log_level: info
+
+# Receive OTLP traces from Alloy and write them through the Kafka-compatible path.
+distributor:
+  ingester_write_path_enabled: false
+  kafka_write_path_enabled: true
+  receivers:
+    otlp:
+      protocols:
+        grpc:
+          endpoint: "tempo:4317"
+        http:
+          endpoint: "tempo:4318"
+  #log_received_spans:
+  #    enabled: true
+  #  log_discarded_spans:
+  #    enabled: true
+
+# Keep trace blocks for 7 days during backend compaction.
+backend_scheduler:
+  provider:
+    compaction:
+      compaction:
+        block_retention: 168h
+
+# Backend workers compact trace blocks and coordinate through memberlist.
+backend_worker:
+  backend_scheduler_addr: backend-scheduler:3200
+  compaction:
+    block_retention: 168h
+  ring:
+    kvstore:
+      store: memberlist
+
+# Enable querying data that is still in the live store.
+querier:
+  query_live_store: true
+
+# Generate Prometheus metrics from spans and service graphs.
+metrics_generator:
+  registry:
+    external_labels:
+      source: tempo
+      cluster: docker-compose
+  storage:
+    path: /var/tempo/generator/wal
+    remote_write:
+      - url: http://prometheus:9090/api/v1/write
+        send_exemplars: true
+
+# Grafana uses the query frontend for trace search and trace detail views.
+query_frontend:
+  rf1_after: "1999-01-01T00:00:00Z"
+  mcp_server:
+    enabled: true
+
+# Store trace blocks in MinIO and write the local WAL under the data directory.
+storage:
+  trace:
+    backend: s3
+    s3:
+      bucket: tempo
+      endpoint: minio:9000
+      access_key: "{{TELEMETRY_MINIO_ACCESS_KEY}}"
+      secret_key: "{{TELEMETRY_MINIO_SECRET_KEY}}"
+      insecure: true
+    wal:
+      path: /var/tempo/wal
+
+# Turn traces into span metrics and service graph metrics for Grafana.
+overrides:
+  defaults:
+    metrics_generator:
+      processors: ["span-metrics", "service-graphs"]
+      generate_native_histograms: both
+
+# Use Redpanda as the Kafka-compatible ingestion queue for this local stack.
+ingest:
+  enabled: true
+  kafka:
+    address: redpanda:9092
+    topic: tempo-ingest
+
+# Build compacted blocks frequently so demo data appears quickly.
+block_builder:
+  consume_cycle_duration: 30s
+
+# Disable upstream usage reports for this local package.
+usage_report:
+  reporting_enabled: false