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

# Elasticsearch

> Steadwing connects to your Elasticsearch cluster to query logs, metrics, and traces using natural language and ES|QL, so you get root cause analysis without manual log searching.

## What does the Elasticsearch integration do?

The Elasticsearch integration lets Steadwing query your logs, metrics, and traces using natural language and ES|QL during incident analysis, so you get automated root cause analysis instead of manual log searching. Steadwing leverages Kibana's Agent Builder tools to intelligently search your data, identify patterns, and correlate findings with code changes.

## Why Use Elasticsearch with Steadwing?

<CardGroup cols={2}>
  <Card title="Semantic Search" icon="search">
    Query logs using natural language - no complex syntax needed
  </Card>

  <Card title="ES|QL Analysis" icon="database">
    Run powerful analytical queries to aggregate and analyze data
  </Card>

  <Card title="Custom Tools" icon="wrench">
    Leverage your pre-configured Agent Builder tools
  </Card>

  <Card title="Smart Correlation" icon="chart-network">
    Automatically link log patterns to code changes and deployments
  </Card>
</CardGroup>

## How do I connect Elasticsearch to Steadwing?

### Step 1: Get Your Kibana URL

Your Kibana URL format depends on your deployment type:

**Elastic Cloud:**

```text theme={null}
https://your-deployment-id.kb.region.cloud.es.io
```

**Elastic Serverless:**

```text theme={null}
https://your-project.es.region.cloud.es.io
```

**Example:**

```text theme={null}
https://abc123def.kb.us-east-1.aws.found.io
```

### Step 2: Create an API Key

1. Navigate to **Kibana → Stack Management → API Keys**
2. Click **Create API Key**
3. Configure the following privileges:

```json theme={null}
{
  "name": "steadwing-rca-integration",
  "role_descriptors": {
    "steadwing_role": {
      "cluster": ["monitor"],
      "indices": [
        {
          "names": ["logs-*", "metrics-*"],
          "privileges": ["read", "view_index_metadata"]
        }
      ],
      "applications": [
        {
          "application": "kibana-.kibana",
          "privileges": ["read_onechat", "space_read"],
          "resources": ["*"]
        }
      ]
    }
  }
}
```

**Required Privileges:**

* `read_onechat` - Access to Agent Builder MCP
* `space_read` - Access to Kibana spaces
* `read` + `view_index_metadata` - Query your indices

4. Click **Create API Key**
5. **Copy the API key** - you'll need it in Step 3

<Warning>
  Save your API key immediately! It's shown only once. If you lose it, you'll need to create a new key.
</Warning>

### Step 3: Connect Elasticsearch in Steadwing

1. Navigate to [Steadwing Settings](https://app.steadwing.com/settings)
2. Find the **Elasticsearch** integration card
3. Click to expand the collapsible form
4. Fill in the required fields:
   * **Kibana URL:** Your full Kibana instance URL (e.g., `https://abc123def.kb.us-east-1.aws.found.io`)
   * **API Key:** The API key you created
5. Toggle the switch to **Enable** the integration

## What happens when Steadwing queries Elasticsearch?

When analyzing an incident, Steadwing automatically:

1. **Discovers Tools** - Identifies available tools in your Kibana Agent Builder
2. **Extracts Context** - Parses error messages for service names, timestamps, and error types
3. **Queries Strategically:**
   * Semantic search for broad pattern matching
   * ES|QL for detailed aggregations and analysis
   * Custom tools if configured
4. **Correlates Findings** - Combines Elasticsearch data with code changes, metrics, and deployments
5. **Generates Timeline** - Builds chronological view of events leading to the incident

No manual log searching required!

## Requirements

* **Elastic Cloud 9.2+** or **Elastic Serverless** deployment
* Kibana instance with Agent Builder enabled
* API Key with appropriate privileges

## Use Cases

**Error Investigation:**

```text theme={null}
Example: "Show me all errors in the payment service from the last hour"
Steadwing uses semantic search to find relevant error logs automatically
```

**Performance Analysis:**

```text theme={null}
Example: "Find timeout errors related to the database"
ES|QL aggregates timeouts by service and identifies patterns
```

**Deployment Correlation:**

```text theme={null}
Steadwing correlates error spikes with recent deployments
Timeline shows: Deploy → Error spike → Root cause identified
```

## What Data Can Steadwing Access?

**Read-Only Access:**

* Only indices specified in your API key (e.g., `logs-*`, `metrics-*`)
* Time-bounded queries (typically 1-6 hours around incident)
* Limited results (50-100 per query)

**Security:**

* Cannot write, update, or delete data
* Cannot modify Kibana dashboards or settings
* API keys encrypted at rest
* Queries executed in real-time - no data storage

## Uninstall

To disconnect the integration:

1. In Steadwing Settings, disable the Elasticsearch integration
2. In Kibana, delete the API key:
   * Navigate to **Stack Management → API Keys**
   * Find "steadwing-rca-integration" (or your chosen name)
   * Click **Delete**

This immediately revokes access.

## FAQs

<AccordionGroup>
  <Accordion title="Can Steadwing modify my Elasticsearch data?">
    No. The API key only has read permissions. Steadwing cannot write, update, or delete any data in your Elasticsearch cluster.
  </Accordion>

  <Accordion title="What Elasticsearch versions are supported?">
    Elastic Cloud 9.2+ and Elastic Serverless. Older versions are not supported due to Agent Builder requirements.
  </Accordion>

  <Accordion title="Do I need to create custom tools in Agent Builder?">
    No. Steadwing can use semantic search and ES|QL without custom tools. However, custom tools can improve results for organization-specific queries.
  </Accordion>

  <Accordion title="Why am I getting 403 Forbidden errors?">
    Verify your API key includes `read_onechat` and `space_read` privileges. These are required for Agent Builder access.
  </Accordion>

  <Accordion title="How much data does it query?">
    Only data within the incident timeframe (typically 1-6 hours). Queries are limited to 50-100 results to prevent overwhelming data transfer.
  </Accordion>

  <Accordion title="What if I don't have Agent Builder enabled?">
    Agent Builder must be enabled in your Kibana instance. Contact Elastic support to enable it for your deployment.
  </Accordion>

  <Accordion title="Can I scope access to specific indices?">
    Yes. In the API key privileges, specify only the indices you want Steadwing to access (e.g., `logs-production-*` instead of `logs-*`).
  </Accordion>

  <Accordion title="Does this work with on-premises Elasticsearch?">
    Currently, only Elastic Cloud 9.2+ and Elastic Serverless are supported. On-premises deployments require these versions with Agent Builder enabled.
  </Accordion>
</AccordionGroup>

Need additional help? Please reach out to us at [hello@steadwing.com](mailto:hello@steadwing.com)