feat: add instrumentation

Dockerfile.cpu

@@ -3,19 +3,19 @@ LABEL org.opencontainers.image.source="https://github.com/fedirz/faster-whisper-
 # `ffmpeg` is installed because without it `gradio` won't work with mp3(possible others as well) files
 # hadolint ignore=DL3008
 RUN apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ffmpeg python3.12 && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+  DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ffmpeg python3.12 && \
+  apt-get clean && \
+  rm -rf /var/lib/apt/lists/*
 COPY --from=ghcr.io/astral-sh/uv:0.5.9 /uv /bin/uv
 WORKDIR /root/faster-whisper-server
 # https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
 RUN --mount=type=cache,target=/root/.cache/uv \
-    --mount=type=bind,source=uv.lock,target=uv.lock \
-    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
-    uv sync --frozen --no-install-project
+  --mount=type=bind,source=uv.lock,target=uv.lock \
+  --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+  uv sync --frozen --no-install-project
 COPY ./src ./pyproject.toml ./uv.lock ./
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --extra ui
+  uv sync --frozen --extra ui
 ENV WHISPER__MODEL=Systran/faster-whisper-small
 ENV UVICORN_HOST=0.0.0.0
 ENV UVICORN_PORT=8000

Dockerfile.cuda

@@ -3,20 +3,20 @@ LABEL org.opencontainers.image.source="https://github.com/fedirz/faster-whisper-
 # `ffmpeg` is installed because without it `gradio` won't work with mp3(possible others as well) files
 # hadolint ignore=DL3008
 RUN apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ffmpeg python3.12 && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+  DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends ffmpeg python3.12 && \
+  apt-get clean && \
+  rm -rf /var/lib/apt/lists/*
 COPY --from=ghcr.io/astral-sh/uv:0.5.9 /uv /bin/uv
 WORKDIR /root/faster-whisper-server
 # https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
 RUN --mount=type=cache,target=/root/.cache/uv \
-    --mount=type=bind,source=uv.lock,target=uv.lock \
-    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
-    uv sync --frozen --no-install-project
+  --mount=type=bind,source=uv.lock,target=uv.lock \
+  --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+  uv sync --frozen --no-install-project
 COPY ./src ./pyproject.toml ./uv.lock ./
 RUN --mount=type=cache,target=/root/.cache/uv \
-    uv sync --frozen --extra ui
+  uv sync --frozen --extra ui --extra opentelemetry
 ENV WHISPER__MODEL=Systran/faster-whisper-large-v3
 ENV UVICORN_HOST=0.0.0.0
 ENV UVICORN_PORT=8000
-CMD ["uv", "run", "uvicorn", "--factory", "faster_whisper_server.main:create_app"]
+CMD ["uv", "run", "opentelemetry-instrument", "uvicorn", "--factory", "faster_whisper_server.main:create_app"]

Taskfile.yaml

@@ -3,7 +3,7 @@ tasks:
   server:
     cmds:
       - pkill --signal SIGKILL --echo --full 'uvicorn --factory --host 0.0.0.0 faster_whisper_server.main:create_app' || true
-      - uvicorn --factory --host 0.0.0.0 faster_whisper_server.main:create_app {{.CLI_ARGS}}
+      - opentelemetry-instrument uvicorn --factory --host 0.0.0.0 faster_whisper_server.main:create_app {{.CLI_ARGS}}
     sources:
       - src/**/*.py
   test:

compose.yaml

@@ -1,4 +1,6 @@
 # TODO: https://docs.astral.sh/uv/guides/integration/docker/#configuring-watch-with-docker-compose
+include:
+  - observability-compose.yaml
 services:
   faster-whisper-server-cuda:
     image: fedirz/faster-whisper-server:latest-cuda

configuration/grafana/datasources.yaml

@@ -0,0 +1,23 @@
+apiVersion: 1
+datasources:
+  - name: tempo
+    type: tempo
+    access: proxy
+    url: http://tempo:3200
+    editable: true
+    jsonData:
+      tracesToLogsV2:
+        datasourceUid: loki
+        filterByTraceID: true
+      lokiSearch:
+        datasourceUid: loki
+  - name: loki
+    type: loki
+    access: proxy
+    url: http://loki:3100
+    editable: true
+  - name: prometheus
+    type: prometheus
+    editable: true
+    url: http://prometheus:9090
+# TODO: https://grafana.com/docs/tempo/latest/getting-started/metrics-from-traces/

configuration/loki.yaml

@@ -0,0 +1,41 @@
+# https://github.com/grafana/loki/blob/811f5f015cd5da4e25d800307b905c3385406be3/docs/sources/configure/examples/configuration-examples.md
+
+auth_enabled: false # default: true
+# https://grafana.com/docs/loki/latest/configure/#server
+server:
+  http_listen_port: 3100 # default: 3100
+  grpc_listen_port: 9095 # default: 9095
+  log_level: info # default: info
+  log_format: json # default: logfmt
+limits_config:
+  allow_structured_metadata: true # needed for OTEL
+  volume_enabled: true # not sure what this does
+common:
+  ring:
+    instance_addr: 0.0.0.0
+    kvstore:
+      store: inmemory
+  replication_factor: 1
+  path_prefix: /tmp/loki
+storage_config:
+  tsdb_shipper:
+    active_index_directory: /tmp/loki/index
+    cache_location: /tmp/loki/index_cache
+  filesystem:
+    directory: /tmp/loki/chunks
+pattern_ingester:
+  enabled: true
+analytics:
+  reporting_enabled: false # default: true
+tracing:
+  enabled: true # default: false
+# https://grafana.com/docs/loki/latest/configure/#schema_config
+schema_config:
+  configs:
+    - from: 2020-05-15
+      store: tsdb
+      object_store: filesystem
+      schema: v13
+      index:
+        prefix: index_
+        period: 24h

configuration/opentelemetry-collector.yaml

@@ -0,0 +1,46 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+processors:
+  batch:
+exporters:
+  otlp/tempo:
+    endpoint: http://tempo:4317
+    tls:
+      insecure: true
+  prometheus:
+    endpoint: 0.0.0.0:8889
+  otlphttp/loki:
+    # https://github.com/grafana/loki/issues/5346
+    # endpoint: http://loki:3100/otlp/v1/logs
+    endpoint: http://loki:3100/otlp
+    tls:
+      insecure: true
+  debug:
+    verbosity: detailed
+extensions:
+  health_check:
+    endpoint: 0.0.0.0:13133 # default port
+service:
+  extensions: [health_check]
+  telemetry:
+    logs:
+      level: debug
+      # development: true
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlp/tempo]
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [prometheus]
+    logs:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [otlphttp/loki]

configuration/prometheus.yaml

@@ -0,0 +1,6 @@
+global:
+  scrape_interval: 5s
+scrape_configs:
+  - job_name: "opentelemetry-collector"
+    static_configs:
+      - targets: ["opentelemetry-collector:8889"]

configuration/tempo.yaml

@@ -0,0 +1,19 @@
+server:
+  http_listen_port: 3200 # default: 80
+  grpc_listen_port: 9095 # default: 9095
+
+usage_report:
+  reporting_enabled: false
+
+distributor:
+  receivers:
+    otlp:
+      protocols:
+        grpc:
+
+# TODO: S3 storage
+storage:
+  trace:
+    backend: local
+    local:
+      path: /tmp/tempo/traces

observability-compose.yaml

@@ -0,0 +1,73 @@
+services:
+  opentelemetry-collector:
+    image: otel/opentelemetry-collector-contrib:0.107.0
+    command: ["--config=/etc/opentelemetry-collector.yaml"]
+    volumes:
+      - ./configuration/opentelemetry-collector.yaml:/etc/opentelemetry-collector.yaml
+    ports:
+      # NOTE: when `faster-whisper-server` is also running as a Docker Compose service, this doesn't need to be exposed.
+      - 4317:4317 # OTLP gRPC receiver
+      # - 4318:4318 # OTLP HTTP receiver
+      # - 8888:8888 # Prometheus metrics exposed by the Collector
+      # - 8889:8889 # Prometheus exporter metrics
+      # - 13133:13133 # health_check extension
+    # NOTE: `healthcheck` can't be set up, as the container doesn't have a shell to run the healthcheck command.
+  loki:
+    image: grafana/loki:3.0.0
+    command: ["-config.file=/etc/loki.yaml"]
+    volumes:
+      - ./configuration/loki.yaml:/etc/loki.yaml
+      - loki-data:/loki
+    ports:
+      - "3100:3100"
+    healthcheck:
+      # NOTE: doesn't have a proper healthcheck endpoint
+      test: wget --no-verbose --tries=1 --spider http://localhost:3100/ready || exit 1
+      interval: 5s
+      timeout: 5s
+      retries: 3
+  prometheus:
+    image: prom/prometheus:v2.55.0
+    command: ["--config.file=/etc/prometheus.yaml"]
+    volumes:
+      - ./configuration/prometheus.yaml:/etc/prometheus.yaml
+      - prometheus-data:/prometheus
+    healthcheck:
+      test: wget --no-verbose --tries=1 --spider http://localhost:9090/-/healthy || exit 1
+      interval: 5s
+      timeout: 5s
+      retries: 3
+  tempo:
+    image: grafana/tempo:2.5.0
+    command: ["-config.file=/etc/tempo.yaml"]
+    volumes:
+      - ./configuration/tempo.yaml:/etc/tempo.yaml
+      - tempo-data:/tmp
+      # https://github.com/grafana/tempo/issues/1657#issuecomment-2049987178
+      # - tempo-data:/tmp/tempo
+    healthcheck:
+      test: wget --no-verbose --tries=1 --spider http://localhost:3200/status || exit 1
+      interval: 5s
+      timeout: 5s
+      retries: 3
+  grafana:
+    image: grafana/grafana:11.3.0
+    volumes:
+      - ./configuration/grafana/datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml
+      - grafana-data:/var/lib/grafana
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+      - GF_AUTH_DISABLE_LOGIN_FORM=true
+    ports:
+      - "3000:3000"
+    healthcheck:
+      test: wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1
+      interval: 5s
+      timeout: 5s
+      retries: 3
+volumes:
+  loki-data:
+  prometheus-data:
+  tempo-data:
+  grafana-data:

pyproject.toml

@@ -43,6 +43,20 @@ ui = [
     "httpx-sse>=0.4.0",
     "openai>=1.48.0",
 ]
+opentelemetry = [
+    "opentelemetry-distro>=0.48b0",
+    "opentelemetry-exporter-otlp>=1.27.0",
+    "opentelemetry-instrumentation-asyncio==0.48b0",
+    "opentelemetry-instrumentation-logging==0.48b0",
+    "opentelemetry-instrumentation-threading==0.48b0",
+    "opentelemetry-instrumentation-urllib==0.48b0",
+    # "opentelemetry-instrumentation-wsgi==0.48b0"
+    "opentelemetry-instrumentation-fastapi==0.48b0",
+    "opentelemetry-instrumentation-grpc==0.48b0",
+    "opentelemetry-instrumentation-httpx==0.48b0",
+    "opentelemetry-instrumentation-requests==0.48b0",
+    "opentelemetry-instrumentation-urllib3==0.48b0",
+]
 
 [build-system]
 requires = ["hatchling"]