### Start Reverse Proxy Example with Docker Compose

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/reverse-proxy/README.md

Command to start all three reverse proxy use cases using Docker Compose. Ensure you are in the 'examples/reverse-proxy' directory and specify the Jaeger image.

```sh
cd examples/reverse-proxy
JAEGER_IMAGE=cr.jaegertracing.io/jaegertracing/jaeger:latest docker compose up
```

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

### Start Services with Docker Compose

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/grafana-integration/README.md

Starts all the necessary services for the Grafana integration example using docker compose.

```bash
docker compose up
```

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

### Run Development Environment

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/tail-sampling/README.md

Execute this command to start the Jaeger and OpenTelemetry collector services for the example.

```bash
make dev
```

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

### Install Dependencies with uv

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/gemini/README.md

Use `uv sync` to install all required dependencies for the sidecar. This is the only supported method.

```bash
uv sync
```

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

### Clean Install of Observability Stack

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/otel-demo/README.md

Execute this command for a fresh installation, which removes previous releases and namespaces before deploying everything.

```bash
./deploy-all.sh clean
```

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

### Storage Extension Start Method

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/003-lazy-storage-factory-initialization.md

Validates configuration for all trace backends during the Start phase. It creates uninitialized factories and performs configuration validation without establishing connections.

```go
type storageExt struct {
    config           *Config
    telset           component.TelemetrySettings
    factories        map[string]tracestore.Factory
    initialized      map[string]bool
    initMu           sync.Mutex  // Serializes initialization
    // ...
}

func (s *storageExt) Start(ctx context.Context, host component.Host) error {
    for storageName, cfg := range s.config.TraceBackends {
        // Phase 1: Configuration only - validate without connecting
        factory, err := storageconfig.CreateUninitializedFactory(ctx, storageName, cfg, telset)
        if err != nil {
            return fmt.Errorf("invalid configuration for storage '%s': %w", storageName, err)
        }
        if configurable, ok := factory.(ConfigurableFactory); ok {
            if err := configurable.Configure(ctx); err != nil {
                return fmt.Errorf("configuration validation failed for storage '%s': %w", storageName, err)
            }
        }
        s.factories[storageName] = factory
    }
    return nil
}
```

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

### Start OpenSearch Docker Compose

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/monitor/README.md

Use this command to start the Jaeger system with OpenSearch as the storage backend.

```shell
docker compose -f docker-compose-opensearch.yml up
```

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

### Start Jaeger Server

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/README.md

Command to start the Jaeger server with the specified configuration.

```bash
go run ./cmd/jaeger --config config.yaml
```

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

### Upgrade or Install Observability Stack

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/otel-demo/README.md

This command installs the stack if it's missing or upgrades it if it's already present. It's the default behavior.

```bash
./deploy-all.sh
# or explicitly
./deploy-all.sh upgrade
```

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

### Sample Output for get_services

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/002-mcp-server.md

Example JSON output for the 'get_services' MCP tool, showing a list of available service names.

```json
{
  "services": ["payment-service", "payment-gateway", "payment-processor"]
}
```

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

### Dry-run Output Example

Source: https://github.com/jaegertracing/jaeger/blob/main/internal/config/tlscfg/testdata/README.md

This is an example of the output you will see when running 'make certs-dryrun', indicating where the generated certificate files are located.

```bash
# Dry-run complete. Generated files can be found in /var/folders/3p/yms48z2s6v7c8fy2m_1481g00000gn/T/certificates.p7pFHXpy
```

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

### List Services in Jaeger Instance

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegermcp/README.md

Example query to list all services registered in the Jaeger instance.

```shell
which services are in my Jaeger instance
```

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

### Sample Input for get_services

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/002-mcp-server.md

Example JSON input for the 'get_services' MCP tool, demonstrating optional filtering by pattern and limiting results.

```json
{
  "pattern": "payment",        // optional: substring filter
  "limit": 100                 // optional: max results (default: 100)
}
```

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

### Run The Sidecar Server

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/gemini/README.md

Start the sidecar server using the `uv run python main.py` command. The expected startup log indicates the listening address.

```bash
uv run python main.py
```

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

### Initialize MCP Inspector

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegermcp/README.md

Command to start the MCP Inspector using npx.

```shell
npx @modelcontextprotocol/inspector
```

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

### Search Traces Output

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/002-mcp-server.md

Example output from the search_traces API, returning lightweight metadata for matching traces, including trace ID, root service and span, start time, duration, span count, service count, and error status.

```json
{
  "traces": [
    {
      "trace_id": "1a2b3c4d5e6f7890",
      "root_service": "frontend",
      "root_span_name": "/api/checkout",
      "start_time": "2024-01-15T10:30:00Z",
      "duration_us": 2450000,
      "span_count": 47,
      "service_count": 8,
      "has_errors": true
    }
  ]
}
```

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

### Initialize Submodules and Install Tools

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

After cloning, initialize the jaeger-ui submodule and install necessary development tools using the Makefile. This ensures all dependencies and tools are ready for development.

```bash
# Adds the jaeger-ui submodule
git submodule update --init --recursive

# Installs required tools
make install-tools
```

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

### Start Elasticsearch Docker Compose

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/monitor/README.md

Use this command to start the Jaeger system with Elasticsearch as the storage backend.

```shell
docker compose -f docker-compose-elasticsearch.yml up
```

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

### Start AI Sidecar Provider

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/README.md

Command to start the AI sidecar, setting the necessary API key and running the Python main script.

```bash
cd scripts/ai-sidecar/myprovider
export OPENAI_API_KEY=...   # or whichever provider
uv run python main.py
```

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

### Run tracegen Docker Image

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/tracegen/README.md

Example of how to run the tracegen Docker image to generate traces. Adjust service name and trace count as needed.

```sh
docker run jaegertracing/jaeger-tracegen -service abcd -traces 10
```

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

### Run Sidecar Server with Runtime Flags

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/gemini/README.md

Start the sidecar server with specific runtime flags for host, port, MCP URL, discovery timeout, and OTLP endpoint configuration.

```bash
uv run python main.py \
  --host localhost --port 16688 \
  --mcp-url http://127.0.0.1:16687/mcp \
  --mcp-discovery-timeout-sec 15 \
  --otlp-endpoint http://localhost:4317 --otlp-insecure
```

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

### Go SDK Example Panel Definition

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/007-grafana-dashboards-modernization.md

An example of defining a Grafana timeseries panel using the Go SDK's fluent builder API. This snippet demonstrates how to set the panel title and add Prometheus data queries for success and error rates.

```go
func spanIngestPanel() *timeseries.PanelBuilder {
    return timeseries.NewPanelBuilder().
        Title("Span Ingest Rate").
        WithTarget(prometheus.NewDataqueryBuilder().
            Expr(`sum(rate(otelcol_receiver_accepted_spans_total[1m]))`).
            LegendFormat("success")),
        WithTarget(prometheus.NewDataqueryBuilder().
            Expr(`sum(rate(otelcol_receiver_refused_spans_total[1m])) or vector(0)`).
            LegendFormat("error"))
}
```

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

### Example OTLP Endpoint Configuration

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/gemini/README.md

Example of pointing the OTLP endpoint to a remote collector with TLS enabled. The `--no-otlp-insecure` flag is used to enforce TLS.

```bash
uv run python main.py \
  --otlp-endpoint https://otel.example.com:4317 \
  --no-otlp-insecure
```

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

### Download docker-compose.yml

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/README.md

Use curl to download the docker-compose.yml file for the Jaeger HotROD example.

```bash
curl -O https://raw.githubusercontent.com/jaegertracing/jaeger/refs/heads/main/examples/hotrod/docker-compose.yml
```

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

### Optional Configuration Validation

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/003-lazy-storage-factory-initialization.md

Adds an optional configuration validation step during the `Start` method to detect invalid configurations early. This requires adding `Validate()` methods to backend configurations.

```go
func (s *storageExt) Start(ctx context.Context, host component.Host) error {
    s.host = host
    // Optional: validate configurations without initializing
    for name, cfg := range s.config.TraceBackends {
        if err := cfg.Validate(); err != nil {
            return fmt.Errorf("invalid configuration for storage '%s': %w", name, err)
        }
    }
    return nil
}
```

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

### Run HotROD from Source

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/hotrod/README.md

This command clones the Jaeger repository and then runs the HotROD demo application from its source code using `go run`. The `all` argument starts all HotROD services.

```bash
git clone git@github.com:jaegertracing/jaeger.git jaeger
cd jaeger
go run ./examples/hotrod/main.go all
```

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

### Set Gemini API Key Environment Variable

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/gemini/README.md

Set your Gemini API key before starting the server. Without this key, the sidecar cannot create the Gemini client.

```bash
export GEMINI_API_KEY="your_api_key_here"
```

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

### Example .nocover File Content

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Shows the content of a .nocover file, which is used to exclude packages from code coverage calculations. The file should contain a comment explaining the reason for exclusion.

```text
requires connection to Cassandra
```

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

### Spin up Jaeger Infrastructure with ScyllaDB

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/scylladb/README.md

Starts the ScyllaDB cluster, generates the Jaeger keyspace schema, and launches the Jaeger server, UI, and Demo App using Docker Compose.

```shell
docker compose up -d
```

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

### Deprecated Flag Help Text Example

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Shows how to use the deprecation warning constant as a prefix for the help text when defining a flag using flagSet.Int.

```go
flagSet.Int(healthCheckHTTPPort, 0, healthCheckHTTPPortWarning+" see --"+adminHTTPHostPort)
```

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

### Initialize Submodules

Source: https://github.com/jaegertracing/jaeger/blob/main/CLAUDE.md

Run this command when checking out a fresh repository to initialize all submodules.

```bash
git submodule update --init --recursive
```

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

### Deploy HotROD with Default Configuration

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/hotrod/kubernetes/README.md

Navigate to the examples/oci directory and run the clean script to deploy with default settings.

```bash
cd examples/oci
./deploy-all.sh clean
```

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

### Stop Services with Docker Compose

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/grafana-integration/README.md

Shuts down all services started by docker compose for the Grafana integration example.

```bash
docker compose down
```

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

### Get Full OTLP Span Data Output Example

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/002-mcp-server.md

Example of the detailed OTLP span data returned by the get_span_details endpoint. It includes span ID, trace ID, service information, timestamps, status, attributes, events, and links.

```json
{
  "trace_id": "1a2b3c4d5e6f7890",
  "spans": [
    {
      "span_id": "span_C",
      "trace_id": "1a2b3c4d5e6f7890",
      "parent_span_id": "span_A",
      "service": "payment-service",
      "span_name": "processPayment",
      "start_time": "2024-01-15T10:30:00.200Z",
      "duration_us": 2200000,
      "status": {
        "code": "ERROR",
        "message": "Upstream service timeout"
      },
      "attributes": {
        "http.method": "POST",
        "http.url": "http://payment-gateway/charge",
        "http.status_code": "504",
        "retry.count": "3"
      },
      "events": [
        {
          "name": "retry_attempt",
          "timestamp": "2024-01-15T10:30:00.700Z",
          "attributes": {"attempt": "1"}
        },
        {
          "name": "retry_attempt",
          "timestamp": "2024-01-15T10:30:01.200Z",
          "attributes": {"attempt": "2"}
        }
      ],
      "links": []
    },
    {
      "span_id": "span_D",
      "trace_id": "1a2b3c4d5e6f7890",
      "parent_span_id": "span_C",
      "service": "payment-gateway",
      "span_name": "chargeCard",
      "start_time": "2024-01-15T10:30:00.250Z",
      "duration_us": 2100000,
      "status": {
        "code": "ERROR",
        "message": "Connection timeout to payment processor"
      },
      "attributes": {
        "db.system": "postgresql",
        "db.statement": "SELECT * FROM transactions WHERE...",
        "net.peer.name": "payment-db.internal",
        "net.peer.port": "5432"
      },
      "events": [],
      "links": []
    }
  ]
}
```

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

### Get Trace Topology Output

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/002-mcp-server.md

Output from the get_trace_topology API, providing a flat list of spans with their path, service, span name, start time, duration, and status. This format is optimized for LLM context by excluding attributes and events.

```json
{
  "trace_id": "1a2b3c4d5e6f7890",
  "spans": [
    {
      "path": "span_A",
      "service": "frontend",
      "span_name": "/api/checkout",
      "start_time": "2024-01-15T10:30:00Z",
      "duration_us": 2450000,
      "status": "OK"
    },
    {
      "path": "span_A/span_B",
      "service": "cart-service",
      "span_name": "getCart",
      "start_time": "2024-01-15T10:30:00.050Z",
      "duration_us": 120000,
      "status": "OK"
    },
    {
      "path": "span_A/span_C",
      "service": "payment-service",
      "span_name": "processPayment",
      "start_time": "2024-01-15T10:30:00.200Z",
      "duration_us": 2200000,
      "status": "ERROR"
    },
    {
      "path": "span_A/span_C/span_D",
      "service": "payment-gateway",
      "span_name": "chargeCard",
      "start_time": "2024-01-15T10:30:00.250Z",
      "duration_us": 2100000,
      "status": "ERROR"
    }
  ]
}
```

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

### Install GNU sed on macOS

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

If you are running 'make test' or other Makefile targets on macOS, you may need to install GNU sed. This command installs it using Homebrew.

```bash
brew install gnu-sed
```

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

### Deploy Jaeger Demo Setup with Helm

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/oci/README.md

Use this command to deploy the entire Jaeger demo infrastructure, including Jaeger, HotROD, Prometheus, and a load generator. Refer to the deploy-all.sh script for individual component deployment details.

```bash
bash ./deploy-all.sh
```

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

### Install Loki Docker Driver Plugin

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/grafana-integration/README.md

Installs the Loki logging plugin for Docker, which is required for all services to log to Loki.

```bash
docker plugin install \
grafana/loki-docker-driver:latest \
--alias loki \
--grant-all-permissions
```

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

### Remove Deprecated CLI Flag Example

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Example of how to document the removal of a deprecated CLI flag in the changelog, indicating the replacement flag.

```markdown
* Remove deprecated flags `--old-flag`, please use `--new-flag` ([#1234](<pull-request URL>), [@myusername](https://github.com/myusername))
```

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

### No Cover Build Error Example

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Illustrates the error message generated by the 'make nocover' build step when a directory contains Go files but no test files, enforcing the requirement for at least one *_test.go file.

```text
error: at least one *_test.go file must be in all directories with go files
       so that they are counted for code coverage.
       If no tests are possible for a package (e.g. it only defines types), create empty_test.go
```

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

### Start jaeger-remote-storage with Badger Backend

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/remote-storage/README.md

Launches the remote storage binary using a configuration file that specifies the Badger storage backend. Ensure 'config-badger.yaml' is correctly set up for Badger storage.

```bash
./jaeger-remote-storage --config-file config-badger.yaml
```

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

### Deprecated Flag Warning Message Example

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Provides an example of a deprecation message for CLI flags, indicating when the flag will be removed and suggesting a future release or date.

```go
"(deprecated, will be removed after 2020-03-15 or in release v1.19.0, whichever is later)"
```

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

### Cassandra Factory New Method

Source: https://github.com/jaegertracing/jaeger/blob/main/docs/adr/003-lazy-storage-factory-initialization.md

Constructor for the Cassandra factory, initializing it with options and telemetry settings. It does not establish a connection at this stage.

```go
type Factory struct {
    config     cassandra.Options
    telset     telemetry.Settings
    session    cassandra.Session  // nil until initialized
    configured bool
    initialized bool
}

func NewFactory(opts cassandra.Options, telset telemetry.Settings) (*Factory, error) {
    return &Factory{
        config: opts,
        telset: telset,
    }, nil
}
```

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

### Run All Unit Tests

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Execute all unit tests for the project using the 'make test' command. This is a crucial step to ensure code quality and correctness before submitting changes.

```bash
# Runs all unit tests:
make test
```

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

### Troubleshoot Certificate Issues

Source: https://github.com/jaegertracing/jaeger/blob/main/examples/otel-demo/ingress/README.md

Use these kubectl commands to investigate certificate-related problems. 'describe certificate' shows details and events for a specific certificate, while 'get certificaterequest' and 'get challenge' show the status of related resources managed by cert-manager.

```bash
kubectl describe certificate <cert-name> -n <namespace>
```

```bash
kubectl get certificaterequest -n <namespace>
```

```bash
kubectl get challenge -n <namespace>
```

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

### Run Jaeger Locally with UI

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Start a local Jaeger instance with the UI enabled. This command uses the default configuration file, which includes UI integration via the 'jaeger_query' extension. The UI assets are managed by the 'jaeger-ui' submodule.

```bash
$ go run ./cmd/jaeger --config ./cmd/jaeger/config.yaml
```

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

### Go Import Grouping Example

Source: https://github.com/jaegertracing/jaeger/blob/main/CONTRIBUTING.md

Demonstrates the standard pattern for grouping imports in Go files within the Jaeger project, separating standard library, other projects, and Jaeger project imports.

```go
import (
	"fmt"

	"github.com/uber/jaeger-lib/metrics"
	"go.uber.org/zap"

	"github.com/jaegertracing/jaeger/cmd/agent/app"
	"github.com/jaegertracing/jaeger/cmd/collector/app/builder"
)
```

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

### Example Contextual Tools Snapshot

Source: https://github.com/jaegertracing/jaeger/blob/main/scripts/ai-sidecar/README.md

This JSON structure shows the format of the contextual tools snapshot received in the `_meta` field during a `session/new` request. It includes a list of UI tools with their names, descriptions, and parameter schemas.

```json
{
  "_meta": {
    "jaegertracing.io/contextual-tools": {
      "tools": [
        {
          "name": "ui_show_flamegraph",
          "description": "Open the flamegraph view for a given trace_id.",
          "parameters": { "type": "object", "properties": { ... } }
        }
      ]
    }
  }
}
```

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

### GET /api/metrics/minstep

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/monitor/README.md

Fetches the minimum step size supported by the underlying metrics store.

```APIDOC
## GET /api/metrics/minstep

### Description
Fetches the minimum step size supported by the underlying metrics store.

### Method
GET

### Endpoint
/api/metrics/minstep

### Parameters
None

### Request Example
```bash
curl "http://localhost:16686/api/metrics/minstep"
```

### Response
#### Success Response (200)
- **minStep** (long) - The minimum step size in milliseconds supported by the metrics store.

#### Response Example
```json
{
  "minStep": 1000
}
```
```

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

### GET /api/metrics/errors

Source: https://github.com/jaegertracing/jaeger/blob/main/docker-compose/monitor/README.md

Fetches error rates for specified services using default parameters.

```APIDOC
## GET /api/metrics/errors

### Description
Fetches error rates for specified services using default parameters.

### Method
GET

### Endpoint
/api/metrics/errors

### Parameters
#### Query Parameters
- **service** (string) - Required - The service name to query metrics for. Can be specified multiple times.

### Request Example
```bash
curl "http://localhost:16686/api/metrics/errors?service=driver&service=frontend"
```

### Response
#### Success Response (200)
- **data** (array) - An array of metric data points.
  - **serviceName** (string) - The name of the service.
  - **operationName** (string) - The name of the operation.
  - **value** (number) - The calculated error rate.
  - **timestamp** (long) - The timestamp of the data point.

#### Response Example
```json
{
  "data": [
    {
      "serviceName": "driver",
      "operationName": "DeleteOrder",
      "value": 0.01,
      "timestamp": 1678886400000
    }
  ]
}
```
```

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

### Start jaeger-remote-storage with Memory Backend

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/remote-storage/README.md

Launches the remote storage binary using a configuration file that specifies the memory storage backend. Ensure 'config.yaml' is correctly set up for memory storage.

```bash
./jaeger-remote-storage --config-file config.yaml
```

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

### Identify Errors in Longest Trace

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegermcp/README.md

Example query to find the number of errors in the longest trace.

```shell
how many errors in the longest trace?
```

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

### Count Traces for a Service

Source: https://github.com/jaegertracing/jaeger/blob/main/cmd/jaeger/internal/extension/jaegermcp/README.md

Example query to count the number of traces for a specific service within the last hour.

```shell
how many traces  for frontend service
```