OpenSearch Integration
Connect OpenSearch to let agents search logs, read index mappings, and run PPL and SQL log queries directly during investigations. You can also forward OpenSearch alerting monitor notifications to Autoheal via webhook. Autoheal ingests and groups them, and makes them available for triage on the Alerts page.
This integration works with self-hosted OpenSearch and Amazon OpenSearch Service (managed domains).
OpenSearch vs. Elasticsearch — pick the right card. OpenSearch forked from Elasticsearch 7.10 and is a different product. It uses the PPL/SQL query languages (not Elasticsearch's ES|QL) and a different auth model. Use this card for OpenSearch. Use the Elasticsearch card for an Elasticsearch cluster. If you point this card at an Elasticsearch cluster, Test Connection will warn you.
Capabilities
Once connected, agents can:
| Capability | Description |
|---|---|
| Search Logs | Run the full query DSL with filters, aggregations, sorting, and pagination (opensearch_search) |
| Query Logs (PPL/SQL) | Run piped PPL (default) or SQL log queries (opensearch_query) — the OpenSearch equivalent of ES|QL |
| Browse Indices | List indices and their document counts (opensearch_list_indices) |
| Read Mappings | Inspect an index's field mappings so agents build correct queries (opensearch_get_mappings) |
| Inspect Shards | Check shard allocation and health (opensearch_get_shards) |
| Test Connection | Check the endpoint, the credentials, and that it's really OpenSearch (opensearch_test_connection) |
| Alert Source Webhooks | Receive OpenSearch alerting monitor notifications via webhook, mapped to Autoheal alerts |
Prerequisites
- An OpenSearch cluster endpoint reachable by Autoheal (see Private and on-prem access if it is not internet-reachable)
- Credentials matching how your cluster is protected: basic (OpenSearch Security user), bearer/JWT, or AWS IAM (Amazon OpenSearch Service)
- A read-only OpenSearch role for the account you connect (see Required Permissions)
Setup
- Add the Integration in Autoheal
- Go to Integrations in Autoheal and click OpenSearch
- Enter a name that identifies the cluster/environment — e.g.
OpenSearch – prod
- Enter the Endpoint
- OpenSearch Endpoint: the cluster base URL (not OpenSearch Dashboards), e.g.
https://opensearch.internal:9200. - For Amazon OpenSearch Service, use the domain endpoint, e.g.
https://search-mydomain-abc123.us-east-1.es.amazonaws.com.
- OpenSearch Endpoint: the cluster base URL (not OpenSearch Dashboards), e.g.
- Choose Authentication
Pick the auth type that matches your cluster:
- Username & Password — an OpenSearch Security user with read access
- Bearer Token (JWT) — OpenSearch Security JWT or a reverse-proxy token
- AWS IAM (SigV4) — Amazon OpenSearch Service via a linked AWS integration (see below)
- Test and Save
Click Test Connection to check the endpoint and credentials, then Save. Test Connection reports the cluster version and warns if the endpoint is actually an Elasticsearch cluster.
Authentication Options
| Auth type | When to use | Fields |
|---|---|---|
| Username & Password | OpenSearch Security internal/LDAP user | Username, Password |
| Bearer Token (JWT) | OpenSearch Security JWT or reverse-proxy token | Bearer Token |
| AWS IAM (SigV4) | Amazon OpenSearch Service (managed domain) | AWS Integration, Region |
AWS IAM (SigV4)
For Amazon OpenSearch Service, Autoheal signs each request with AWS SigV4 using credentials from a linked AWS integration. The OpenSearch integration stores no long-lived keys.
- Connect an AWS integration
Add the AWS integration (OIDC federation or instance role). Its IAM role must be allowed on your OpenSearch domain's access policy / fine-grained access control (a read-only role is enough).
- Select AWS IAM (SigV4) on OpenSearch
- AWS Integration: pick the AWS integration from step 1
- Region: the domain's AWS region (leave blank to use the AWS integration's region)
Required Permissions
Grant Autoheal a read-only role. The integration only reads. It never writes, updates, or deletes. A typical OpenSearch Security role:
| Permission | Scope | Why it's needed |
|---|---|---|
cluster:monitor/* | Cluster | Test connection, cluster health, shard status |
indices:data/read/* | Log indices | Search and PPL/SQL queries |
indices:admin/mappings/get | Log indices | Read field mappings |
indices:monitor/* | Log indices | Index/shard stats |
Restrict the role's index patterns to the log indices Autoheal should see (e.g. logs-*) rather than *.
Example Queries
Once connected, you can ask an agent questions like:
Show the last 50 ERROR logs for host vm-42 in the last hour
Count errors by service in the app-logs index over the last 15 minutes
Using PPL, find OutOfMemoryError entries and group them by host
What indices are available, and what fields does the app-logs mapping have?
Alert Source Setup
OpenSearch's alerting plugin can POST a notification to a webhook when a monitor triggers. Because you author the message body template in full, you map its fields to Autoheal alert fields in the Alert Payload Mapping. The mapping starts empty. Configure it to match your body, and use the recommended template below as a starting point.
- Enable the Webhook in Autoheal
- Open your OpenSearch integration in Autoheal
- In the Events Setup section, copy the Webhook URL (it already contains a unique per-integration secret)
- Optionally enter a Webhook Signing Secret for a Bearer-token check on every delivery
- Create a Notifications Channel in OpenSearch
In OpenSearch Dashboards → Notifications, create a Custom webhook channel:
- URL: the Autoheal Webhook URL
- Content type:
application/json - If you set a Webhook Signing Secret, add a header
Authorization: Bearer <the same secret>
- Set the Monitor Action Message
In your monitor's trigger action, select that channel. Set the message body to this recommended template. Then map its fields in the Payload Mapping:
JSON{
"identity": "{{ctx.monitor.name}}::{{ctx.trigger.name}}",
"title": "{{ctx.trigger.name}} on {{ctx.monitor.name}}",
"severity": "{{ctx.trigger.severity}}",
"monitor": "{{ctx.monitor.name}}",
"trigger": "{{ctx.trigger.name}}"
}warningThe body must be valid JSON (escape quotes as OpenSearch requires). To scope an alert to a host/VM, add a field from your query results (e.g.
"host": "{{ctx.results.0.hits.hits.0._source.host}}"). Then add a matching label row in the Payload Mapping. This scope lets agents pull that host's logs. - Preview and Test
Use Preview in the mapping editor to paste a sample body and check the resulting alert. Then trigger the monitor. The alert should appear on Autoheal's Alerts page within a few seconds.
OpenSearch alerting fires on trigger. By default, it does not send a "resolved" signal, so mapped alerts stay open until they expire. To auto-resolve, add a status field to your message body and map it (Status + Resolved Values) in the Payload Mapping.
Private and on-prem access
This applies to Autoheal's SaaS deployment. In a BYOC deployment the stack runs inside your own network and reaches OpenSearch directly by endpoint. As a result, the Private Access connection field is not shown.
Query routing over a Private Access connection runs inside the agent sandbox and is enabled per organization. To enable it, contact support. See Private Access.
If your OpenSearch is on a private network and not reachable from the internet, alert delivery still works. OpenSearch makes an outbound call to the Webhook URL. But queries need a path into your network:
- Add a Private Access connection
Follow the Tailscale guide to add a connection (Tailscale) and join the host or subnet running OpenSearch to your private network.
- Bind OpenSearch to it
In the OpenSearch integration, set Private Access connection to the connection you created. Queries for this instance then route over your private network to the endpoint.
Only integrations you explicitly bind to a Private Access connection route through it. Everything else continues to reach public endpoints directly.
Troubleshooting
Test Connection warns it may be an Elasticsearch cluster
You pointed the OpenSearch card at an Elasticsearch cluster. Use the Elasticsearch integration instead. The query languages and auth differ.
401 / 403 on Test Connection
- Check that the Auth type matches how your cluster is protected (Basic vs Bearer vs AWS IAM)
- For Basic, re-enter the username and password (watch for trailing spaces). Check that the user has the read-only role
- For AWS IAM, check that the linked AWS integration's role is granted on the domain's access policy / fine-grained access control. Also check that the Region is correct
PPL/SQL query fails
- PPL starts with
source=<index> | .... SQL usesFROM <index> - The SQL/PPL plugin ships by default with OpenSearch and Amazon OpenSearch Service. If it's disabled, use
opensearch_search(query DSL) instead
Connection timeout / cannot reach endpoint
- Check that the Endpoint is the cluster URL (port 9200 for self-hosted), not OpenSearch Dashboards
- If OpenSearch is on a private network, add and bind a Private Access connection. This step applies to SaaS deployments. See Private and on-prem access
Webhook alerts not appearing
- Check that the channel URL exactly matches the Webhook URL in Autoheal, with content type
application/json - Use Preview in the mapping editor to check that your message body maps to a valid alert (at minimum an Identity and Title)
- If you set a Webhook Signing Secret, check that the channel sends the matching
Authorization: Bearerheader