> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nofire.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Jaeger

> Connect your Jaeger instance with NOFire AI

<Info>
  Jaeger is not offered in **Add Connection** today. If you already have a Jaeger connection, it keeps working. Contact support with questions.
</Info>

Connect your Jaeger instance to NOFire AI. NOFire AI can then query and analyze distributed traces across Kubernetes and microservices environments. It uses these traces for investigation and automated root cause analysis.

<Info>
  NOFire AI supports both self-hosted Jaeger instances and managed Jaeger deployments. For self-hosted instances, NOFire AI can connect securely using an AWS VPC PrivateLink. This keeps all traffic inside your network boundary.
</Info>

## Prerequisites

Before you connect Jaeger to NOFire AI, make sure that you have:

* A running Jaeger instance (self-hosted or managed)
* Network access to your Jaeger Query Service from NOFire AI
* The Jaeger Query Service API endpoint (typically port 16686)
* Authentication credentials (if you use a reverse proxy)

## Step 1: Check the Jaeger deployment

### Option A: Self-hosted Jaeger

<Accordion title="Check the Jaeger Query Service" defaultOpen>
  1. **Check Jaeger Services**: Make sure that all Jaeger components are running:
     * **Jaeger Agent**: Receives spans from instrumented applications
     * **Jaeger Collector**: Receives spans from agents and writes them to storage
     * **Jaeger Query Service**: Provides the UI and API to retrieve traces
     * **Storage Backend**: Cassandra, Elasticsearch, or in-memory storage

  2. **Open the Jaeger UI**: go to the URL of your Jaeger Query Service:
     ```
     http://your-jaeger-host:16686
     ```

  3. **Test API Access**: Make sure that the Jaeger Query Service API is accessible:

     ```bash theme={null}
     curl http://your-jaeger-host:16686/api/services
     ```

     The command returns a JSON response with a list of services.

  4. **Note Your Endpoint**: Your Jaeger Query Service endpoint is:

     ```
     http://your-jaeger-host:16686
     ```

     For HTTPS, the endpoint is:

     ```
     https://your-jaeger-host:16686
     ```
</Accordion>

### Option B: Kubernetes deployment

<Accordion title="Access Jaeger in Kubernetes" defaultOpen={false}>
  1. **Check the deployment**: make sure that Jaeger is running in your cluster:
     ```bash theme={null}
     kubectl get pods -n observability -l app=jaeger
     ```

  2. **Get the Jaeger Query Service**: Find the service:
     ```bash theme={null}
     kubectl get service -n observability jaeger-query
     ```

  3. **Expose the Jaeger Query Service** (if it is not already exposed):

     **Option 1: LoadBalancer Service**

     ```bash theme={null}
     kubectl patch svc jaeger-query -n observability -p '{"spec": {"type": "LoadBalancer"}}'
     ```

     **Option 2: Ingress**

     ```yaml theme={null}
     apiVersion: networking.k8s.io/v1
     kind: Ingress
     metadata:
       name: jaeger-ingress
       namespace: observability
     spec:
       rules:
       - host: jaeger.mycompany.com
         http:
           paths:
           - path: /
             pathType: Prefix
             backend:
               service:
                 name: jaeger-query
                 port:
                   number: 16686
     ```

  4. **Get the External Endpoint**:
     * For LoadBalancer: `kubectl get svc jaeger-query -n observability`
     * For Ingress: Use the hostname configured in your ingress (for example, `https://jaeger.mycompany.com`)
</Accordion>

### Option C: Jaeger operator

<Accordion title="Configure Jaeger Operator" defaultOpen={false}>
  1. **Check the instance**: if you use the Jaeger Operator, make sure that your Jaeger instance is running:
     ```bash theme={null}
     kubectl get jaeger -n observability
     ```

  2. **View the Jaeger Query Service**:
     ```bash theme={null}
     kubectl get service -n observability -l app.kubernetes.io/component=query
     ```

  3. **Configure Ingress**: If you configure it, the Jaeger Operator can create ingress routes automatically:
     ```yaml theme={null}
     apiVersion: jaegertracing.io/v1
     kind: Jaeger
     metadata:
       name: my-jaeger
       namespace: observability
     spec:
       ingress:
         enabled: true
         hosts:
           - jaeger.mycompany.com
     ```
</Accordion>

## Step 2: Configure authentication (optional)

Jaeger Query Service does not have built-in authentication, but you can secure it using a reverse proxy.

<Accordion title="Setup Reverse Proxy with Authentication" defaultOpen={false}>
  ### Using Nginx as Reverse Proxy

  1. **Install Nginx**: Deploy Nginx as a reverse proxy in front of Jaeger.

  2. **Configure Basic Authentication**:
     ```nginx theme={null}
     server {
         listen 443 ssl;
         server_name jaeger.mycompany.com;

         ssl_certificate /etc/nginx/ssl/cert.pem;
         ssl_certificate_key /etc/nginx/ssl/key.pem;

         location / {
             auth_basic "Jaeger Access";
             auth_basic_user_file /etc/nginx/.htpasswd;
             
             proxy_pass http://jaeger-query:16686;
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
         }
     }
     ```

  3. **Create an htpasswd file**:
     ```bash theme={null}
     htpasswd -c /etc/nginx/.htpasswd nofireai-user
     ```

  ### Using OAuth2 Proxy

  For more advanced authentication (OAuth2, OIDC):

  ```yaml theme={null}
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: oauth2-proxy
  spec:
    template:
      spec:
        containers:
        - name: oauth2-proxy
          image: quay.io/oauth2-proxy/oauth2-proxy:latest
          args:
          - --provider=oidc
          - --upstream=http://jaeger-query:16686
          - --http-address=0.0.0.0:4180
  ```
</Accordion>

## Step 3: Add Jaeger connection to NOFire AI

<Accordion title="Navigate to the Connections Tab" defaultOpen>
  1. Jaeger is not offered in **Add Connection** today (see the note above). The fields below are for reference if you are troubleshooting an existing connection or have questions for support:

     * **Name**: Enter a descriptive name (for example, "production-jaeger")
     * **Jaeger Query URL**: Enter your Jaeger Query Service endpoint
       * Self-hosted Example: `http://jaeger.mycompany.com:16686`
       * Kubernetes Ingress Example: `https://jaeger.mycompany.com`
       * Internal Kubernetes Example: `http://jaeger-query.observability.svc.cluster.local:16686`

     **Authentication Options (if you use a reverse proxy):**

     For Basic Authentication:

     * **Username**: Enter the username (for example, `nofireai-user`)
     * **Password**: Enter the password

     For Bearer Token Authentication:

     * **Authorization Header**: Enter `Bearer <your-token>`

  2. Once a Jaeger connection is in place, NOFire AI queries and analyzes traces on demand, as part of automated root cause analysis. NOFire AI uses these traces to show service dependencies, latencies, and error propagation.
</Accordion>

## Understanding Jaeger data in NOFire AI

<Accordion title="How NOFire AI Uses Jaeger Traces" defaultOpen={false}>
  NOFire AI uses Jaeger traces to map your distributed system:

  ### 1. Service Dependency Mapping

  * Automatically constructs service dependency graphs from trace data
  * Identifies upstream and downstream dependencies
  * Maps service communication patterns

  ### 2. Latency Analysis

  * Analyzes span durations to identify slow operations
  * Compares latencies across different services
  * Detects performance regressions

  ### 3. Error Propagation Tracking

  * Traces errors across service boundaries
  * Identifies the origin of failures
  * Maps how errors cascade through the system

  ### 4. Root Cause Analysis

  * Correlates traces with logs and metrics
  * Identifies which service caused an incident
  * Provides evidence-based recommendations
</Accordion>

## Test the connection

1. Open the **Connections** dashboard and make sure that the Jaeger connection status is **READY**. A connection that stays in an error state did not authenticate.
2. Ask NOFire a question that needs traces, for example "show me the slowest traces for the checkout service in the last hour". An answer that cites trace IDs confirms the connection works end to end.

## Troubleshooting

<Accordion title="Common Issues" defaultOpen={false}>
  ### Connection Timeout

  If you have connection timeouts:

  * Make sure that your Jaeger Query Service is accessible from the NOFire AI network
  * Make sure that port 16686 is open and accessible
  * Make sure that firewall rules allow traffic from NOFire AI
  * Test the connection: `curl http://your-jaeger-host:16686/api/services`

  ### Authentication Failed

  If authentication fails:

  * Make sure that the username and password are correct (if you use basic auth)
  * Make sure that the Authorization header is formatted correctly for bearer tokens
  * Make sure that the reverse proxy is configured correctly

  ### No Traces Found

  If no traces appear:

  * Make sure that your applications are instrumented and send traces to Jaeger
  * Make sure that traces appear in the Jaeger UI
  * Make sure that the Jaeger Collector and Agent are running
  * Make sure that the storage backend is working (Elasticsearch, Cassandra, and more)
  * Make sure that the sampling configuration is not too aggressive

  ### Incomplete Traces

  If traces are incomplete or spans are missing:

  * Make sure that all services are instrumented correctly
  * Make sure that context propagation headers pass between services
  * Make sure that the Jaeger Agent has enough resources
  * Review the trace sampling rates

  ### SSL Certificate Errors

  For HTTPS endpoints with SSL errors:

  * Make sure that your SSL certificate is valid and not self-signed (or add it to your trusted certificates)
  * Make sure that the hostname in the URL matches the certificate
  * Make sure that the certificate chain is complete
</Accordion>

## Best practices

<Info>
  * **Security**: Always use HTTPS and authentication for production deployments
  * **Sampling**: Configure sampling rates that balance data volume and coverage
  * **Storage**: Provide enough storage for your trace retention needs
  * **Performance**: Monitor Jaeger component resources (Agent, Collector, Query)
  * **Instrumentation**: Instrument all critical services for complete trace visibility
  * **Context Propagation**: Make sure that services propagate trace context correctly across boundaries
  * **Network Security**: Use VPC PrivateLink or VPN for secure connectivity to self-hosted instances
</Info>

## Configuration examples

### Self-hosted Jaeger (no authentication)

```
URL: http://jaeger.mycompany.com:16686
Username: (leave empty)
Password: (leave empty)
```

### Self-hosted Jaeger with basic auth

```
URL: https://jaeger.mycompany.com
Username: nofireai-user
Password: <your-secure-password>
```

### Kubernetes internal service

```
URL: http://jaeger-query.observability.svc.cluster.local:16686
Username: (leave empty)
Password: (leave empty)
```

### Jaeger with bearer token

```
URL: https://jaeger.mycompany.com
Authorization Header: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## Additional resources

* [Jaeger Official Documentation](https://www.jaegertracing.io/docs/)
* [Jaeger Operator Documentation](https://www.jaegertracing.io/docs/latest/operator/)
* [OpenTelemetry Integration](https://opentelemetry.io/docs/instrumentation/)
* [Jaeger Performance Tuning](https://www.jaegertracing.io/docs/latest/performance-tuning/)

## Related documentation

* [Tempo Integration](/traces/tempo) - Alternative distributed tracing backend