Korrel8r

https://korrel8r.github.io/korrel8r/
Admin
Korrel8r is a rule-based correlation engine for Kubernetes clusters that correlates observability...
Tokens:19,989
Snippets:289
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install korrel8rcli

Source: https://korrel8r.github.io/korrel8r/docs/client

Command to install the purpose-built command line client.

```bash
go install github.com/korrel8r/client/cmd/korrel8rcli@latest
```

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

### Kubernetes Resource Class Examples

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/k8s

Examples of valid Kubernetes resource class strings.

```text
k8s:Pod
k8s:Pod.v1
k8s:Deployment.apps
k8s:Deployment.v1.apps
k8s:Route.v1.route.openshift.io
```

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

### Kubernetes Query Examples

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/k8s

Examples of JSON selectors used for querying Kubernetes resources.

```json
k8s:Pod.v1:{"namespace":"some-namespace", "name":"some-name"}
k8s:Deployment.v1:{"labels":{"app":"my-application"}, "namespace":"some-namespace" }
```

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

### GET /help and GET /help/{domain} Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns documentation text for all domains or a specific domain.

```json
{
   "documentation": "gObD0iOtQN"
}
```

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

### Install Korrel8r CLI

Source: https://korrel8r.github.io/korrel8r/docs/getting-started

Installs the Korrel8r command line tool using Go.

```bash
go install github.com/korrel8r/korrel8r/cmd/korrel8r@latest
```

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

### GET /help/{domain}

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns full documentation for a single domain.

```APIDOC
## GET /help/{domain}

### Description
Returns full documentation for a single domain, including class names, query syntax, and examples.

### Method
GET

### Endpoint
/help/{domain}

### Parameters
#### Path Parameters
- **domain** (string) - Required - Name of the domain to get help for

### Response
#### Success Response (200)
- **documentation** (string) - Full documentation text for one or more domains.

#### Response Example
{
   "documentation": "gObD0iOtQN"
}
```

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

### POST /graphs/goals Request

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Example request body for specifying start objects and goal classes to find correlation paths.

```json
{
   "goals": [
      "k8s:Pod",
      "metric:metric"
   ],
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}
```

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

### Use korrel8rcli

Source: https://korrel8r.github.io/korrel8r/docs/client

Examples of using the CLI to query domains, neighbors, and goals.

```bash
# Check what data sources are available
korrel8rcli -u $KORREL8R_URL domains

# Find everything related to a deployment
korrel8rcli -u $KORREL8R_URL neighbors --query 'k8s:Deployment:{namespace: korrel8r}'

# Find all logs related to a deployment
korrel8rcli -u $KORREL8R_URL goals --start 'k8s:Deployment:{namespace: korrel8r}' --goal 'log:application'
```

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

### GET /help

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns full documentation for all correlation domains.

```APIDOC
## GET /help

### Description
Returns full documentation for all correlation domains, including class names, query syntax, and examples.

### Method
GET

### Endpoint
/help

### Response
#### Success Response (200)
- **documentation** (string) - Full documentation text for one or more domains.

#### Response Example
{
   "documentation": "gObD0iOtQN"
}
```

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

### Container Selector Examples

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/log

Examples of using container selectors to filter logs by namespace, labels, and specific containers.

```json
log:application:{ "namespace": "something", "labels":{"app": "myapp"}, "containers":["foo", "bar"]}
log:infrastructure:{ "namespace": "openshift-kube-apiserver", "containers":["kube-apiserver"]}
```

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

### Run korrel8r web command

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_web

Basic syntax for starting the korrel8r web server.

```bash
korrel8r web [flags]
```

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

### LogQL Query Example

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/log

An example of a LogQL expression used to query stored infrastructure logs.

```text
log:infrastructure:{kubernetes_namespace_name="openshift-cluster-version", kubernetes_pod_name=~".*-operator-.*"}
```

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

### Alert Query Examples

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/alert

Examples of querying alerts using label selectors, supporting both single object filters and arrays for OR-logic matching.

```text
alert:alert:{"container":"kube-rbac-proxy-main","namespace":"openshift-logging"}
alert:alert:[{"alertname":"alert1"},{"alertname":"alert2"}]
```

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

### Setup Claude Code with Korrel8r

Source: https://korrel8r.github.io/korrel8r/docs/ai-agents

Commands and configuration to integrate Claude Code with a local Korrel8r instance.

```bash
oc login <cluster-url>
```

```bash
curl -o korrel8r.yaml https://raw.githubusercontent.com/korrel8r/korrel8r/main/etc/korrel8r/openshift-route.yaml
```

```json
{
  "mcpServers": {
    "korrel8r": {
      "command": "korrel8r",
      "args": ["--config", "korrel8r.yaml", "mcp"]
    }
  }
}
```

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

### Run as MCP Tool

Source: https://korrel8r.github.io/korrel8r/docs/command

Execute the command to start the tool in MCP mode for integration with local AI agents.

```bash
korrel8r mcp
```

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

### POST /lists/goals

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

This endpoint accepts a set of start objects (as queries or serialized objects) and a goal class. It returns a list of all objects of the goal class that can be reached from the provided start objects.

```APIDOC
## POST /lists/goals

### Description
Specify a set of start objects, as queries or serialized objects, and a goal class. Returns a list of all objects of the goal class that can be reached from a start object.

### Method
POST

### Endpoint
/lists/goals

### Request Body
- **goals** (array of Class) - Required - Goal classes in DOMAIN:CLASS format, e.g. log:application, alert:alert
- **start** (object) - Optional - Starting point for the search.

### Request Example
{
   "goals": [
      "k8s:Pod",
      "metric:metric"
   ],
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}

### Response
#### Success Response (200)
- **array** (object) - List of reachable objects of the goal class.

#### Response Example
[
   {
      "class": "h3S7gYekwH",
      "count": 79,
      "queries": [
         {
            "count": 99,
            "query": {},
            "statuses": []
         }
      ],
      "result": [
         {}
      ]
   }
]
```

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

### Start Korrel8r in web mode

Source: https://korrel8r.github.io/korrel8r/docs/ai-agents

Run Korrel8r as a web service to support remote MCP connections via HTTP.

```bash
korrel8r web --http :8080
```

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

### POST /graphs/goals

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Specify a set of start objects and a goal class to retrieve a graph containing all paths leading from a start object to a goal object.

```APIDOC
## POST /graphs/goals

### Description
Specify a set of start objects, as queries or serialized objects, and a goal class. Returns a graph containing all paths leading from a start object to a goal object.

### Method
POST

### Endpoint
/graphs/goals

### Parameters
#### Query Parameters
- **options** (object) - Optional - Options controlling the form of the returned graph.

#### Request Body
- **goals** (array of Class) - Required - Goal classes in DOMAIN:CLASS format.
- **start** (object) - Required - Starting point for the search.

### Request Example
{
   "goals": [
      "k8s:Pod",
      "metric:metric"
   ],
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}

### Response
#### Success Response (200)
- **edges** (array of Edge) - List of graph edges.
- **nodes** (array of Node) - List of graph nodes.

#### Response Example
{
   "edges": [
      {
         "goal": {},
         "rules": [
            {
               "name": "3gDk8Bg7W9",
               "queries": []
            }
         ],
         "start": {}
      }
   ],
   "nodes": [
      {
         "class": "LLxq2zGNO6",
         "count": 32,
         "queries": [
            {
               "count": 99,
               "query": {},
               "statuses": []
            }
         ],
         "result": [
            {}
         ]
      }
   ]
}
```

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

### GET /domains

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns a list of Korrel8r domains and the stores configured for each domain.

```APIDOC
## GET /domains

### Description
Returns a list of Korrel8r domains and the stores configured for each domain.

### Method
GET

### Endpoint
/domains

### Response
#### Success Response (200)
- **Array** - List of domains and their stores

#### Response Example
[
   {
      "description": "GyAVmNkB33",
      "name": "Z5zQu9MxNm",
      "stores": [
         {}
      ]
   }
]
```

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

### Query Metrics with PromQL

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/metric

Examples of PromQL queries used to extract label matchers for correlation.

```text
metric:metric:kube_pod_info{namespace="default"}
metric:metric:{namespace="tracing-app-k6",pod="k6-tracing-564cf6dc8b-hpxd2"}
```

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

### GET /domains Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns a list of configured Korrel8r domains and their associated stores.

```json
[
   {
      "description": "GyAVmNkB33",
      "name": "Z5zQu9MxNm",
      "stores": [
         {}
      ]
   }
]
```

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

### GET /metrics

Source: https://korrel8r.github.io/korrel8r/docs/reference/metrics

Retrieves the current state of all system metrics in Prometheus format.

```APIDOC
## GET /metrics

### Description
Exposes system metrics for scraping by Prometheus or other monitoring tools.

### Method
GET

### Endpoint
/metrics
```

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

### GET /console 200 Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns the current console state including search and view configurations.

```json
{
   "search": {
      "goals": {
         "goals": [
            "k8s:Pod",
            "metric:metric"
         ],
         "start": {
            "class": {},
            "constraint": {
               "end": "2017-07-21T17:32:28.1341231Z",
               "limit": 100,
               "queryLimit": 10,
               "start": "2024-01-15T10:30:00Z"
            },
            "objects": [],
            "queries": [
               "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
            ]
         }
      },
      "neighbors": {
         "depth": 46,
         "start": {
            "class": {},
            "constraint": {
               "end": "2017-07-21T17:32:28.1341231Z",
               "limit": 100,
               "queryLimit": 10,
               "start": "2024-01-15T10:30:00Z"
            },
            "objects": [],
            "queries": [
               "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
            ]
         }
      }
   },
   "view": {}
}
```

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

### GET /console 404 Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Error response when no console state is available.

```json
{
   "error": "An error occurred"
}
```

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

### POST /graphs/neighbors

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Specify a set of start objects and a depth for the neighborhood search to return a graph of all paths with depth or less edges leading from start objects.

```APIDOC
## POST /graphs/neighbors

### Description
Specify a set of start objects, as queries or serialized objects, and a depth for the neighborhood search. Returns a graph of all paths with depth or less edges leading from start objects.

### Method
POST

### Endpoint
/graphs/neighbors

### Parameters
#### Query Parameters
- **options** (object) - Optional - Options controlling the form of the returned graph.

#### Request Body
- **depth** (integer) - Required - Maximum number of correlation steps to follow from the start.
- **start** (object) - Required - Starting point for the search.

### Request Example
{
   "depth": 8,
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}
```

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

### Correlate Kubernetes selectors to Pods

Source: https://korrel8r.github.io/korrel8r/docs/writing-rules

A rule example that maps various Kubernetes controller types to their corresponding Pods using label selectors.

```yaml
aliases:
  - name: selectors
    domain: k8s
    classes:
      - Service
      - Deployment.apps
      - ReplicaSet.apps
      - StatefulSet.apps

rules:
  - name: SelectorToPods
    start:
      domain: k8s
      classes: [selectors]
    goal:
      domain: k8s
      classes: [Pod]
    result:
      query: |-
        k8s:Pod:{"namespace": "{{.metadata.namespace}}"
        {{- with .spec.selector.matchLabels}}, "labels": {{mustToJson . -}}{{end -}} }
```

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

### GET /objects

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Execute a single Korrel8r query and return the list of serialized objects found.

```APIDOC
## GET /objects

### Description
Execute a single Korrel8r ‘query’ and return the list of serialized objects found. Does not perform any correlation actions.

### Method
GET

### Endpoint
/objects

### Parameters
#### Query Parameters
- **query** (string) - Required - Query string.
- **constraint** (object) - Optional - Constrains the objects that will be included in results.

### Response
#### Success Response (200)
- **Array** - List of serialized objects

#### Response Example
[
   {}
]
```

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

### GET /console/events

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Establishes an SSE stream to receive console updates. The client must provide the same Authorization header as the MCP client.

```APIDOC
## GET /console/events

### Description
Updates are triggered by update requests from the MCP tool show_in_console. This endpoint provides an SSE stream where each event's data field contains a JSON-encoded Console object.

### Method
GET

### Endpoint
/console/events

### Response
#### Success Response (200)
- **data** (JSON) - A JSON-encoded Console object.
```

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

### GET /objects Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns a list of serialized objects resulting from the provided query.

```json
[
   {}
]
```

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

### GET /domain/{domain}/classes

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns a list of class names for the specified domain.

```APIDOC
## GET /domain/{domain}/classes

### Description
Returns a list of class names for the specified domain.

### Method
GET

### Endpoint
/domain/{domain}/classes

### Parameters
#### Path Parameters
- **domain** (string) - Required - Name of the domain to list classes for

### Response
#### Success Response (200)
- **Array** - List of class names

#### Response Example
[
   "Pod",
   "Service",
   "Deployment"
]
```

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

### create_neighbors_graph

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Follows correlation rules outward from start objects up to a given depth.

```APIDOC
## create_neighbors_graph

### Description
Follow correlation rules outward from start objects up to a given depth. Returns a graph of correlated classes with queries and result counts.

### Parameters
#### Input Parameters
- **depth** (integer) - Required - Maximum number of correlation steps to follow.
- **start** (object) - Required - Starting point for the search.

### Output Parameters
- **edges** (object[]) - List of graph edges.
- **nodes** (object[]) - List of graph nodes.
```

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

### Custom Pod phase status rule

Source: https://korrel8r.github.io/korrel8r/docs/statuses

Example of a custom rule to mark Pods not currently in the Running phase.

```yaml
statusRules:
  - name: PodPhase
    start:
      domain: k8s
      classes: [Pod]
    status: |-
      {{- with .status.phase}}{{if ne . "Running"}}{{.}}{{end}}{{end}}
```

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

### GET /domain/{domain}/classes Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns a list of class names available within the specified domain.

```json
[
   "Pod",
   "Service",
   "Deployment"
]
```

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

### POST /graphs/neighbors Request

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Example request body for performing a neighborhood search up to a specified depth.

```json
{
   "depth": 8,
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}
```

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

### GET /console

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Returns the current console state set by a browser client via PUT /console. Enables agents to discover what the user is looking at.

```APIDOC
## GET /console

### Description
Returns the current console state set by a browser client via PUT /console. Enables agents to discover what the user is looking at.

### Method
GET

### Endpoint
/console

### Response
#### Success Response (200)
- **view** (object) - The main console view displays the results of this query.
- **search** (object) - The troubleshooting panel displays the results of this correlation search.

#### Error Response (404)
no console state available
```

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

### Define a basic Korrel8r rule structure

Source: https://korrel8r.github.io/korrel8r/docs/writing-rules

The fundamental YAML structure for a rule, specifying start and goal domains and a Go template for the result query.

```yaml
rules:
  - name: MyRuleName
    start:
      domain: source-domain
      classes:
        - SourceClass
    goal:
      domain: target-domain
      classes:
        - TargetClass
    result:
      query: |-
        target-domain:TargetClass:query-details-template
```

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

### create_goals_graph

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Follows correlation paths from start objects to specific goal classes. Returns a graph of correlated classes with queries and result counts.

```APIDOC
## create_goals_graph

### Description
Follow correlation paths from start objects to specific goal classes. Returns a graph of correlated classes with queries and result counts.

### Parameters
#### Input Parameters
- **goals** (string[]) - Required - Goal classes in DOMAIN:CLASS format.
- **start** (object) - Required - Starting point for the search.

### Output Parameters
- **edges** (object[]) - List of graph edges.
- **nodes** (object[]) - List of graph nodes.
```

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

### Download sample configuration

Source: https://korrel8r.github.io/korrel8r/docs/getting-started

Downloads the default OpenShift route configuration file.

```bash
curl -o korrel8r.yaml https://raw.githubusercontent.com/korrel8r/korrel8r/main/etc/korrel8r/openshift-route.yaml
```

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

### POST /graphs/neighbours

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Performs a neighborhood search starting from a set of objects or queries to return a graph of paths up to a specified depth.

```APIDOC
## POST /graphs/neighbours

### Description
Specify a set of start objects, as queries or serialized objects, and a depth for the neighborhood search. Returns a graph of all paths with depth or less edges leading from start objects.

### Method
POST

### Endpoint
/graphs/neighbours

### Parameters
#### Query Parameters
- **options** (object) - Optional - Options controlling the form of the returned graph.

#### Request Body
- **depth** (integer) - Required - Maximum number of correlation steps to follow from the start.
- **start** (object) - Required - Starting point for the search.

### Request Example
{
   "depth": 8,
   "start": {
      "class": {},
      "constraint": {
         "end": "2017-07-21T17:32:28.1341231Z",
         "limit": 100,
         "queryLimit": 10,
         "start": "2024-01-15T10:30:00Z"
      },
      "objects": [
         {}
      ],
      "queries": [
         "k8s:Pod:{\"namespace\":\"default\",\"name\":\"my-pod\"}"
      ]
   }
}

### Response
#### Success Response (200)
- **edges** (array) - List of graph edges.
- **nodes** (array) - List of graph nodes.

#### Response Example
{
   "edges": [
      {
         "goal": {},
         "rules": [
            {
               "name": "3gDk8Bg7W9",
               "queries": []
            }
         ],
         "start": {}
      }
   ],
   "nodes": [
      {
         "class": "LLxq2zGNO6",
         "count": 32,
         "queries": [
            {
               "count": 99,
               "query": {},
               "statuses": []
            }
         ],
         "result": [
            {}
         ]
      }
   ]
}
```

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

### List and Describe Domains and Classes

Source: https://korrel8r.github.io/korrel8r/docs/command

Use these commands to explore available domains and classes within the cluster configuration.

```bash
# List available domains
korrel8r list

# List classes in the k8s domain
korrel8r list k8s

# Get documentation for a domain
korrel8r describe k8s
```

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

### Load configuration via command line

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Specify the configuration source using the --config flag.

```bash
korrel8r --config <file_or_url>
```

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

### Querying Observability Stores with Korrel8r

Source: https://korrel8r.github.io/korrel8r/docs/other-uses

Demonstrates using a consistent command-line interface to query Kubernetes resources, Loki logs, and Prometheus metrics.

```bash
# Kubernetes resources
korrel8r objects --query 'k8s:Pod:{namespace: myapp}'

# Logs from Loki
korrel8r objects --query 'log:application:{kubernetes_namespace_name="myapp"}'

# Prometheus metrics
korrel8r objects --query 'metric:metric:{namespace="myapp"}'
```

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

### Command-specific options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_stores

Help flag available for the stores command.

```bash
  -h, --help   help for stores
```

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

### Usage syntax for korrel8r stores

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_stores

Basic command structure for listing stores by domain.

```bash
korrel8r stores [DOMAIN...] [flags]
```

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

### Deploy development images

Source: https://korrel8r.github.io/korrel8r/docs/getting-started

Deploys the latest development images to the korrel8r namespace using kustomize.

```bash
oc apply -k github.com/korrel8r/korrel8r/config/?version=main
```

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

### korrel8r list command syntax

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_list

Basic usage syntax for listing domains or classes.

```bash
korrel8r list [DOMAIN] [flags]
```

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

### MCP command help options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_mcp

Displays help information for the mcp command.

```bash
  -h, --help   help for mcp
```

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

### korrel8r describe command syntax

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_describe

Basic usage pattern for the describe command.

```bash
korrel8r describe [DOMAIN] [flags]
```

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

### Command options for objects

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_objects

Available flags for configuring query limits, timeouts, and time ranges.

```bash
  -h, --help               help for objects
      --limit int          Limit total number of results.
      --since duration     Only get results since this long ago.
      --timeout duration   Timeout for store requests.
      --until duration     Only get results until this long ago.
```

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

### View built-in configuration structure

Source: https://korrel8r.github.io/korrel8r/docs/configuration

The default configuration directory contains store definitions and rule sets.

```text
/etc/korrel8r/
├── openshift-route.yaml   # Out-of-cluster: connect to stores via OpenShift routes
├── openshift-svc.yaml     # In-cluster: connect to stores via service URLs
└── rules/
    ├── all.yaml            # Includes all rule files below
    ├── k8s.yaml
    ├── alert.yaml
    ├── log.yaml
    ├── netflow.yaml
    ├── trace.yaml
    └── incident.yaml
```

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

### help

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Provides help on domains, classes, and query syntax.

```APIDOC
## help

### Description
Get help on domains, classes, and query syntax.

### Parameters
#### Input Parameters
- **domain** (string) - Optional - If specified, get help for this domain only.

### Output Parameters
- **documentation** (string) - Required - Domain documentation including query syntax and examples.
```

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

### korrel8r version command usage

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_version

Basic syntax for executing the version command.

```bash
korrel8r version [flags]
```

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

### korrel8r web command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_web

Configuration flags for the web server, including TLS settings, protocol enablement, and observability endpoints.

```bash
      --cert string                 TLS certificate file (PEM format) for https
  -h, --help                        help for web
      --http string                 host:port address for insecure http listener
      --https string                host:port address for secure https listener
      --key string                  Private key (PEM format) for https
      --mcp                         Enable MCP streamable HTTP protocol on /mcp (default true)
      --otel-collector string       URL of OTLP collector endpoint for pushing metrics (e.g. http://localhost:4318/v1/metrics)
      --rest                        Enable HTTP REST server on /api/v1alpha1 (default true)
      --spec string                 Write OpenAPI specification to a file, '-' for stdout.
      --tls-cipher-suites strings   Comma-separated list of TLS cipher suites for https (IANA or OpenSSL names)
      --tls-curves strings          Comma-separated list of TLS curves for https (Go or OpenSSL names, e.g. CurveP256/prime256v1, X25519)
      --tls-min-version string      Minimum TLS version for https (e.g. VersionTLS12, VersionTLS13)
      --unsafe-shared-session       Allow unauthenticated requests to share a single session (UNSAFE: disables per-user isolation)
```

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

### Usage syntax for korrel8r goals

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_goals

Basic command structure for executing the goals command.

```bash
korrel8r goals GOAL [GOAL...] [flags]
```

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

### korrel8r describe command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_describe

Available flags for the describe command.

```bash
  -h, --help   help for describe
```

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

### Include configuration fragments

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Use the include field to reference external configuration files or URLs.

```yaml
include:
  - "path_or_url"
```

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

### korrel8r version command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_version

Available flags for the version command.

```bash
  -h, --help   help for version
```

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

### korrel8r template command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_template

Available flags for specifying template sources.

```bash
  -f, --file string       read template from file
  -h, --help              help for template
  -t, --template string   use template string
```

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

### Mount custom configuration in a deployment

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Mount the ConfigMap as a volume and point the Korrel8r command to the custom configuration file path.

```yaml
volumes:
  - name: custom-config
    configMap:
      name: korrel8r-custom-config
containers:
  - name: korrel8r
    command: ["korrel8r", "web", "--config=/etc/korrel8r/custom/korrel8r.yaml"]
    volumeMounts:
      - name: custom-config
        mountPath: /etc/korrel8r/custom
        readOnly: true
```

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

### Command options for neighbors

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_neighbors

Configuration flags for controlling search depth, object selection, and output content.

```bash
      --class string         Class for serialized start objects
  -d, --depth int            Depth of neighborhood search. (default 3)
      --errors               Include non-fatal errors in graph
  -h, --help                 help for neighbors
      --limit int            Limit total number of results.
      --object stringArray   Serialized start object, can be multiple.
  -q, --query stringArray    Query string for start objects, can be multiple.
      --results              Include complete query results in graph
      --rules                Include rule names in returned graph
      --since duration       Only get results since this long ago.
      --timeout duration     Timeout for store requests.
      --until duration       Only get results until this long ago.
```

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

### Inherited command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_stores

Global configuration and profiling flags inherited from parent commands.

```bash
      --blockprofile file   Write block profile to file
  -c, --config string       Configuration file (default "/etc/korrel8r/korrel8r.yaml")
      --cpuprofile file     Write CPU profile to file
  --httpprofile         Enable pprof HTTP endpoints
  --memprofile file     Write memory profile to file
  --mutexprofile file   Write mutex profile to file
  -o, --output string       One of [json json-pretty ndjson yaml] (default "yaml")
      --trace file          Write execution trace to file
  -v, --verbose int         Verbosity for logging (0: notice/error, 1: info/warn, 2: debug, 3: per-request, 4: per-rule, 5: per-query, 9: extra detail
```

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

### Define and Invoke Reusable Templates

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Defines named templates for reuse and demonstrates how to invoke them using Go template syntax.

```yaml
templates:
  - name: "template_name"       # 1. Name used to invoke the template
    template: "template_body"   # 2. Go template body
```

```text
{{template "template_name" <data>}}
```

```yaml
templates:
  - name: myHelper
    template: 'k8s:{{.class}}:{"namespace":"{{index .labels "namespace"}}"}'

rules:
  - name: MyRule
    start: {domain: alert}
    goal: {domain: k8s, classes: [Pod]}
    result:
      query: '{{template "myHelper" (dict "labels" .Labels "class" "Pod")}}'
```

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

### korrel8r inherited command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_list

Global configuration and profiling options inherited from parent commands.

```bash
      --blockprofile file   Write block profile to file
  -c, --config string       Configuration file (default "/etc/korrel8r/korrel8r.yaml")
      --cpuprofile file     Write CPU profile to file
      --httpprofile         Enable pprof HTTP endpoints
      --memprofile file     Write memory profile to file
      --mutexprofile file   Write mutex profile to file
  -o, --output string       One of [json json-pretty ndjson yaml] (default "yaml")
      --trace file          Write execution trace to file
  -v, --verbose int         Verbosity for logging (0: notice/error, 1: info/warn, 2: debug, 3: per-request, 4: per-rule, 5: per-query, 9: extra detail
```

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

### Configure MCP stdio for agents

Source: https://korrel8r.github.io/korrel8r/docs/ai-agents

Add this configuration to your agent's MCP settings to launch Korrel8r as a subprocess.

```json
{
  "mcpServers": {
    "korrel8r": {
      "command": "korrel8r",
      "args": ["--config", "/path/to/korrel8r.yaml", "mcp"]
    }
  }
}
```

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

### Configure Prometheus Store

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/metric

Configuration format for connecting to a Prometheus store.

```yaml
domain: metric
metric: URL_OF_PROMETHEUS
```

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

### Configure trace store

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/trace

Configuration block for the trace domain, requiring a tempoStack URL.

```yaml
stores:
    domain: trace
    tempoStack: "https://url-of-tempostack"
```

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

### Korrel8r CLI Options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd

Displays the available flags and configuration options for the korrel8r command.

```bash
      --blockprofile file   Write block profile to file
  -c, --config string       Configuration file (default "/etc/korrel8r/korrel8r.yaml")
      --cpuprofile file     Write CPU profile to file
  -h, --help                help for korrel8r
      --httpprofile         Enable pprof HTTP endpoints
      --memprofile file     Write memory profile to file
      --mutexprofile file   Write mutex profile to file
  -o, --output string       One of [json json-pretty ndjson yaml] (default "yaml")
      --trace file          Write execution trace to file
  -v, --verbose int         Verbosity for logging (0: notice/error, 1: info/warn, 2: debug, 3: per-request, 4: per-rule, 5: per-query, 9: extra detail
```

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

### Execute korrel8r objects command

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_objects

Basic syntax for running the objects command with a query.

```bash
korrel8r objects QUERY [flags]
```

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

### Command-specific options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_goals

Flags available for configuring the goals command behavior.

```bash
      --class string         Class for serialized start objects
      --errors               Include non-fatal errors in graph
  -h, --help                 help for goals
      --limit int            Limit total number of results.
      --object stringArray   Serialized start object, can be multiple.
  -q, --query stringArray    Query string for start objects, can be multiple.
      --results              Include complete query results in graph
      --rules                Include rule names in returned graph
      --since duration       Only get results since this long ago.
      --timeout duration     Timeout for store requests.
      --until duration       Only get results until this long ago.
```

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

### korrel8r list command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_list

Available flags for the list command.

```bash
  -h, --help   help for list
```

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

### MCP Tools Reference

Source: https://korrel8r.github.io/korrel8r/docs/ai-agents

A list of available MCP tools for domain exploration, graph generation, query execution, and console management.

```APIDOC
## MCP Tools Reference

| Tool | Description |
| --- | --- |
| `list_domains` | List available domains with descriptions |
| `list_domain_classes` | List classes within a domain |
| `help` | Get documentation and query syntax for a domain (or all domains) |
| `create_goals_graph` | Goal search: find paths from start objects to specific goal classes |
| `create_neighbors_graph` | Neighborhood search: explore all data reachable within N steps |
| `get_objects` | Execute a query and return matching objects |
| `get_console` | Read the current console state (for agent-console navigation) |
| `show_in_console` | Update the console display (for agent-console navigation) |
```

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

### korrel8r template command usage

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_template

Basic syntax for invoking the template command.

```bash
korrel8r template [--file FILE|--template STRING] [flags]
```

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

### Generate a Pod query string

Source: https://korrel8r.github.io/korrel8r/docs/writing-rules

The resulting query string produced by the SelectorToPods rule for a specific Deployment.

```text
k8s:Pod:{"namespace": "myapp", "labels": {"app":"web"}}
```

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

### PUT /config 200 Response

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Successful response for configuration updates.

```json
{}
```

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

### Run korrel8r as an MCP server

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_mcp

Executes the korrel8r MCP server using standard input and output streams.

```bash
korrel8r mcp [flags]
```

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

### korrel8r rules command syntax

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_rules

Basic usage syntax for the rules command.

```bash
korrel8r rules [flags]
```

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

### Configure Kubernetes Store

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/k8s

Configuration block to connect to the currently logged-in kubectl cluster.

```yaml
stores:
    domain: k8s
```

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

### Set configuration environment variable

Source: https://korrel8r.github.io/korrel8r/docs/getting-started

Sets the KORREL8R_CONFIG environment variable to point to the local configuration file.

```bash
export KORREL8R_CONFIG=$PWD/openshift-route.yaml
```

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

### Enable Verbose Logging for Port Selection

Source: https://korrel8r.github.io/korrel8r/docs/reference/user-access

Set the verbosity level to 3 to inspect port selection via CLI or REST API.

```bash
# Using korrel8rcli
korrel8rcli config --set-verbose=3

# Using curl
curl --oauth2-bearer $(oc whoami -t) -X PUT $KORREL8R_URL/api/v1alpha1/config?verbose=3
```

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

### Define Kubernetes Resource Class Format

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/k8s

The format for specifying Kubernetes resource kinds, versions, and groups.

```text
k8s:KIND[.VERSION][.GROUP]
```

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

### Expose Korrel8r Service

Source: https://korrel8r.github.io/korrel8r/docs/client

Commands to create a route for external access to the in-cluster service.

```bash
oc create route reencrypt --service=korrel8r -n openshift-cluster-observability-operator
```

```bash
oc apply -k github.com/korrel8r/korrel8r/config/route?version=main
export KORREL8R_URL=$(oc get route/korrel8r -n openshift-cluster-observability-operator -o template='https://{{.spec.host}}')
```

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

### korrel8r rules command options

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_rules

Available flags for filtering rules and generating graph output.

```bash
  -g, --goal string    show rules with this goal class
      --graph          write rule graph in graphviz format
  -h, --help           help for rules
      --long           show rule start and goal classes
  -n, --name string    show rules with name matching this regexp
  -s, --start string   show rules with this start class
```

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

### Configure NetFlow Stores

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/netflow

Configuration blocks for connecting to LokiStack or plain Loki stores.

```yaml
domain: netflow
lokistack: URL_OF_LOKISTACK_PROXY
```

```yaml
domain: netflow
loki: URL_OF_LOKI
```

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

### Inspect Port Selection Logs

Source: https://korrel8r.github.io/korrel8r/docs/reference/user-access

Filter deployment logs to identify the port currently in use by Korrel8r.

```bash
oc logs -n korrel8r deployment/korrel8r | grep "using.*port"
```

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

### list_domains

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Lists all available domains with descriptions.

```APIDOC
## list_domains

### Description
List available domains with descriptions.

### Output Parameters
- **domains** (object[]) - Required - List of domains.
```

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

### Generate Correlation Graphs

Source: https://korrel8r.github.io/korrel8r/docs/command

Analyze relationships between resources using neighbors or goals commands to output JSON graphs.

```bash
# Get a JSON graph of data related to a deployment within 2 steps
korrel8r neighbors -q 'k8s:Deployment.apps:{namespace: myapp, name: web}' --depth 2

# Get a JSON graph of paths from a deployment to application logs.
korrel8r goals -q 'k8s:Deployment.apps:{namespace: myapp, name: web}' log:application
```

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

### get_console

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Retrieves the current view and search parameters from the console.

```APIDOC
## get_console

### Description
Get what the user is looking at in the console.

### Output Parameters
- **search** (object) - The troubleshooting panel displays the results of this correlation search.
- **view** (string) - Query for the main console view, in DOMAIN:CLASS:SELECTOR format.
```

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

### Log Store Configuration

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/log

Configuration block for defining the log domain store, including LokiStack URL and direct access settings.

```yaml
domain: log
lokiStack: https://URL_OF_DEFAULT_LOKISTACK
direct: true
```

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

### Configure incident store

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/incident

Configuration block for the Prometheus-backed incident store.

```yaml
domain: incident
metrics: PROMETHEUS_URL
```

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

### show_in_console

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Updates the console to display new data.

```APIDOC
## show_in_console

### Description
Update the console to display new data.

### Parameters
#### Input Parameters
- **search** (object) - Optional - The troubleshooting panel displays the results of this correlation search.
- **view** (string) - Optional - Query for the main console view, in DOMAIN:CLASS:SELECTOR format.
```

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

### Define data stores

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Configure connections to data stores by specifying a domain and domain-specific fields.

```yaml
stores:
  - domain: "domain_name"    # 1. Domain name of the store (required)
    # Domain-specific fields # 2. See Domain Reference
```

```yaml
stores:
  - domain: log
    lokiStack: >-
      {{$r := query "k8s:Route.route.openshift.io/v1:{namespace: openshift-logging, name: logging-loki}" -}}
      https://{{ (first $r).Spec.Host -}}
```

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

### PUT /console/events

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Push a console display update to the SSE event stream.

```APIDOC
## PUT /console/events

### Description
Push a console display update to the SSE event stream. The update is delivered to the browser client connected via GET /console/events. Enables agents to direct the console to display specific data.

### Method
PUT

### Endpoint
/console/events
```

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

### Basic usage of korrel8r neighbors

Source: https://korrel8r.github.io/korrel8r/docs/reference/cmd/korrel8r_neighbors

The standard syntax for invoking the neighbors command.

```bash
korrel8r neighbors [flags]
```

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

### Automating Incident Response with Korrel8r

Source: https://korrel8r.github.io/korrel8r/docs/other-uses

Shows how to retrieve correlated data for a specific alert using the neighbors command.

```bash
# Find all data related to a firing alert
korrel8r neighbors --query 'alert:alert:{alertname="HighErrorRate"}' --depth 3
```

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

### Adjust Queries for Non-Admin Users

Source: https://korrel8r.github.io/korrel8r/docs/reference/user-access

Include the namespace in the query string to resolve empty results for non-admin users.

```text
# Before (fails for non-admin Loki alerts)
alert:alert:{"alertname":"MyAlert"}

# After (works for non-admin)
alert:alert:{"alertname":"MyAlert","namespace":"my-namespace"}
```

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

### get_objects

Source: https://korrel8r.github.io/korrel8r/docs/reference/mcp

Executes a query and returns matching objects as JSON.

```APIDOC
## get_objects

### Description
Execute a query and return matching objects as self-contained JSON.

### Parameters
#### Input Parameters
- **constraint** (object) - Optional - Constraint to limit results by time range and/or count.
- **query** (string) - Required - Query string in the form 'domain:class:selector'.
```

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

### Retrieve Cluster Objects

Source: https://korrel8r.github.io/korrel8r/docs/command

Query resources, logs, and metrics using the objects command with specific domain selectors.

```bash
# Print all pods in the default namespace.
korrel8r objects 'k8s:Pod:{namespace: "default"}'

# Print infrastructure logs from the API server.
korrel8r objects 'log:infrastructure:{kubernetes_namespace_name="openshift-kube-apiserver"}'

# Print metrics for the API server.
korrel8r objects 'metric:metric:apiserver_request_total'
```

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

### Define Class Aliases

Source: https://korrel8r.github.io/korrel8r/docs/configuration

Creates short-hand names for groups of classes within a specific domain.

```yaml
aliases:
  - name: "alias_name"       # 1. Can be used wherever a class name is allowed
    domain: "domain_name"    # 2. Domain for classes in this alias
    classes:                  # 3. Classes belonging to this alias
      - "class_name"
```

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

### Configure Verbosity

Source: https://korrel8r.github.io/korrel8r/docs/client

Adjust logging verbosity at runtime using the CLI or REST API.

```bash
korrel8rcli config --set-verbose=9
```

```bash
curl --oauth2-bearer $(oc whoami -t) -X PUT http://localhost:8080/api/v1alpha1/config?verbose=9
```

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

### Query spans using TraceQL

Source: https://korrel8r.github.io/korrel8r/docs/reference/domains/trace

Select spans using a TraceQL query string to filter by resource attributes.

```text
trace:span:{resource.k8s.namespace.name="korrel8r"}
```

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

### Grant Admin RBAC Permissions

Source: https://korrel8r.github.io/korrel8r/docs/reference/user-access

Commands to assign cluster-wide monitoring roles to a user for full observability access.

```bash
# Grant cluster-wide monitoring access (recommended)
oc adm policy add-cluster-role-to-user cluster-monitoring-view <username>

# Alternative: metrics-only access
oc adm policy add-cluster-role-to-user cluster-monitoring-metrics-api <username>
```

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

### PUT /console

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Store console state so an agent can read it via MCP tool get_console.

```APIDOC
## PUT /console

### Description
Store console state so an agent can read it via MCP tool get_console. The MCP client must have the same session (Authorization header) as the REST client.

### Method
PUT

### Endpoint
/console

### Request Body
- **view** (object) - The main console view displays the results of this query.
- **search** (object) - The troubleshooting panel displays the results of this correlation search.

### Response
#### Success Response (200)
Console display updated successfully

#### Error Response (400)
invalid parameters
```

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

### PUT /config

Source: https://korrel8r.github.io/korrel8r/docs/reference/rest

Modify selected configuration settings (e.g. log verbosity) on a running service.

```APIDOC
## PUT /config

### Description
Modify selected configuration settings (e.g. log verbosity) on a running service.

### Method
PUT

### Endpoint
/config

### Parameters
#### Query Parameters
- **verbose** (integer) - Optional - Verbose level for logging.

### Response
#### Success Response (200)
OK
```
Tokens:
Raw