### Enable Prometheus-native Mode via Environment Variables

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Provides example environment variable settings to enable and configure the Prometheus-native metrics backend.

```bash
METRICS_ENABLED=true
METRICS_BACKEND=prometheus
METRICS_PATH=/metrics
```

--------------------------------

### Build Gerbil Binary Locally

Source: https://github.com/fosrl/gerbil/blob/main/README.md

Command to build the Gerbil binary locally. Requires Go 1.26 or later to be installed.

```bash
make local
```

--------------------------------

### Build Gerbil Container Image

Source: https://github.com/fosrl/gerbil/blob/main/README.md

Command to build the Gerbil Docker image. Ensure Docker is installed before running.

```bash
make
```

--------------------------------

### Start OTel Stack with Docker Compose

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Launch the Gerbil service and an OpenTelemetry observability stack using Docker Compose. Ensure OTEL_METRICS_ENDPOINT is correctly configured for the collector.

```bash
METRICS_BACKEND=otel OTEL_METRICS_ENDPOINT=otel-collector:4317 \
  docker compose -f docker-compose.metrics.yml up -d
```

--------------------------------

### Start Prometheus Stack with Docker Compose

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Launch the Gerbil service and a Prometheus observability stack using Docker Compose. The Prometheus scrape endpoint is available at http://localhost:3003/metrics.

```bash
METRICS_BACKEND=prometheus docker-compose -f docker compose.metrics.yml up -d
```

--------------------------------

### Enable Prometheus Metrics via CLI

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Use this command to enable Prometheus metrics collection and specify the backend and path. Metrics are registered when `--metrics-backend=prometheus` is used.

```bash
./gerbil --metrics-enabled --metrics-backend=prometheus --metrics-path=/metrics \
         --config=/etc/gerbil/config.json
```

--------------------------------

### OTel Package Structure for Tracing and Logging

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Shows the directory structure within the OTel package, highlighting where future tracing and logging support can be integrated alongside existing metrics code.

```bash
internal/observability/otel/
  backend.go     ← metrics
  exporter.go    ← OTLP exporter creation
  resource.go    ← OTel resource
  trace.go       ← future: TracerProvider setup
  log.go         ← future: LoggerProvider setup
```

--------------------------------

### Configure OTLP/HTTP Mode for OTel

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Set environment variables to configure OpenTelemetry metrics collection over HTTP. Ensure OTEL_METRICS_ENDPOINT is set to the collector's HTTP port.

```bash
export OTEL_METRICS_PROTOCOL=http
export OTEL_METRICS_ENDPOINT=otel-collector:4318
```

--------------------------------

### Configure Gerbil CLI Arguments via Environment Variables

Source: https://github.com/fosrl/gerbil/blob/main/README.md

Demonstrates how to pass CLI arguments to Gerbil using environment variables. This is useful for scripting or containerized deployments.

```bash
./gerbil \
--reachableAt=http://gerbil:3004 \
--generateAndSaveKeyTo=/var/config/key \
--remoteConfig=http://pangolin:3001/api/v1/
```

--------------------------------

### Configure Gerbil Service in Docker Compose

Source: https://github.com/fosrl/gerbil/blob/main/README.md

Shows how to define a Gerbil service within a Docker Compose file, including image, container name, restart policy, command arguments, volumes, capabilities, and port mappings.

```yaml
services:
  gerbil:
    image: fosrl/gerbil
    container_name: gerbil
    restart: unless-stopped
    command:
      - --reachableAt=http://gerbil:3004
      - --generateAndSaveKeyTo=/var/config/key
      - --remoteConfig=http://pangolin:3001/api/v1/
    volumes:
      - ./config/:/var/config
    cap_add:
      - NET_ADMIN
      - SYS_MODULE
    ports:
      - 51820:51820/udp
      - 21820:21820/udp
      - 443:8443/tcp  # SNI proxy port
```

--------------------------------

### Gerbil Metrics Configuration Struct

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Defines the Go struct for configuring the metrics subsystem, including options for enabling metrics, selecting the backend, and specific configurations for Prometheus and OTel.

```go
type MetricsConfig struct {
    Enabled               bool
    Backend               string // "prometheus" | "otel" | "none"
    Prometheus            PrometheusConfig
    OTel                  OTelConfig
    ServiceName           string
    ServiceVersion        string
    DeploymentEnvironment string
}

type PrometheusConfig struct {
    Path string // default: "/metrics"
}

type OTelConfig struct {
    Protocol       string        // "grpc" (default) or "http"
    Endpoint       string        // default: "localhost:4317"
    Insecure       bool          // default: true
    ExportInterval time.Duration // default: 60s
    Timeout        time.Duration // default: 10s
}
```

--------------------------------

### Enable OTel Mode via Environment Variables

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Configure Gerbil to send metrics to an OpenTelemetry collector using environment variables. Ensure OTEL_METRICS_ENDPOINT is set to your collector's address.

```bash
export METRICS_ENABLED=true
export METRICS_BACKEND=otel
export OTEL_METRICS_PROTOCOL=grpc
export OTEL_METRICS_ENDPOINT=otel-collector:4317
export OTEL_METRICS_INSECURE=true
export OTEL_METRICS_EXPORT_INTERVAL=10s
export OTEL_METRICS_TIMEOUT=10s
export DEPLOYMENT_ENVIRONMENT=production
```

--------------------------------

### Gerbil Metrics CLI Flags

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Lists the available command-line flags for configuring Gerbil's metrics subsystem, including their types and default values.

```bash
--metrics-enabled            bool    (default: true)
--metrics-backend            string  (default: prometheus)
--metrics-path               string  (default: /metrics)
--otel-metrics-protocol      string  (default: grpc)
--otel-metrics-endpoint      string  (default: localhost:4317)
--otel-metrics-insecure      bool    (default: true)
--otel-metrics-export-interval  duration  (default: 60s)
--otel-metrics-timeout          duration  (default: 10s)
```

--------------------------------

### Gerbil Metrics Subsystem Architecture

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Illustrates the flow of metrics from application code through the facade and interface to the selected backend (Prometheus, OTel/OTLP, or Noop).

```text
main.go  ─── internal/metrics  ─── internal/observability  ─── backend
                 (facade)                 (interface)           Prometheus
                                                            OR   OTel/OTLP
                                                            OR   Noop (disabled)
```

--------------------------------

### Enable OTel Mode via CLI

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Configure Gerbil to send metrics to an OpenTelemetry collector using CLI flags. This method overrides environment variables for specific settings.

```bash
./gerbil --metrics-enabled \
         --metrics-backend=otel \
         --otel-metrics-protocol=grpc \
         --otel-metrics-endpoint=otel-collector:4317 \
         --otel-metrics-insecure \
         --otel-metrics-export-interval=10s \
         --otel-metrics-timeout=10s \
         --config=/etc/gerbil/config.json
```

--------------------------------

### Contributor License Agreement (CLA)

Source: https://github.com/fosrl/gerbil/blob/main/CONTRIBUTING.md

Include this text at the beginning of all pull requests to grant project maintainers the necessary licenses for your contributions. This is required for all submissions.

```plaintext
By creating this pull request, I grant the project maintainers an unlimited,
perpetual license to use, modify, and redistribute these contributions under any terms they
choose, including both the AGPLv3 and the Fossorial Commercial license terms. I
represent that I have the right to grant this license for all contributed content.
```

--------------------------------

### Disable Metrics Collection

Source: https://github.com/fosrl/gerbil/blob/main/docs/observability.md

Metrics collection can be disabled by setting METRICS_ENABLED to false, or by setting the metrics backend to 'none'. This ensures no observations are processed.

```bash
export METRICS_ENABLED=false
```

```bash
./gerbil --metrics-enabled=false
```

```bash
./gerbil --metrics-backend=none
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.