OpenSearch / Elasticsearch

HealOps queries OpenSearch (or Elasticsearch) to retrieve application logs, error events, and analytics records — pulling concrete log lines into the investigation alongside metrics and traces from your other observability tools.

Prerequisites

OpenSearch 1.x/2.x or Elasticsearch 7.x/8.x reachable from the machine running HealOps
The cluster URL (e.g. https://my-cluster.us-east-1.es.amazonaws.com)
Credentials for one of:
- HTTP Basic Auth (username and password) — typical for self-hosted OpenSearch
- API key — typical for Elastic Cloud
- No auth — only when the cluster has the security plugin disabled

OpenSearch authenticates clients via Basic Auth by default; the security plugin does not natively issue API keys (opensearch-project/security#4009). Most self-hosted clusters use Basic Auth.

Setup

Option 1: Interactive onboarding wizard

healops onboard

Pick OpenSearch / Elasticsearch from the integration menu. The wizard asks for:

OpenSearch URL — the base URL of your cluster
Authentication method — choose one of:
- Username + Password (default) — for self-hosted OpenSearch with the security plugin enabled
- API key — for Elastic Cloud or clusters with API-key auth configured
- None (security disabled) — for clusters running with the security plugin disabled

The wizard validates the configuration by calling GET /_cluster/health before saving, so you’ll see immediate feedback if the URL or credentials are wrong.

Option 2: Legacy CLI

healops integrations setup opensearch

Same prompts as the wizard, in a smaller standalone form.

Option 3: Environment variables

Add to your .env:

OPENSEARCH_URL=https://my-cluster.example.com

# Basic Auth (typical for self-hosted OpenSearch)
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=secret

# API key (typical for Elastic Cloud — use instead of username/password)
OPENSEARCH_API_KEY=your-api-key

Variable	Default	Description
`OPENSEARCH_URL`	—	Required. Base URL of your OpenSearch / Elasticsearch cluster
`OPENSEARCH_USERNAME`	—	Basic auth username
`OPENSEARCH_PASSWORD`	—	Basic auth password
`OPENSEARCH_API_KEY`	—	API key (used in `Authorization: ApiKey ...` header)

When both OPENSEARCH_API_KEY and Basic Auth credentials are set, the API key takes precedence. If only one of OPENSEARCH_USERNAME / OPENSEARCH_PASSWORD is set, no Authorization header is emitted (the cluster will reject the request, surfacing the misconfiguration).

Option 4: Persistent store

{
  "version": 1,
  "integrations": [
    {
      "id": "opensearch-prod",
      "service": "opensearch",
      "status": "active",
      "credentials": {
        "url": "https://my-cluster.example.com",
        "username": "admin",
        "password": "secret",
        "api_key": "",
        "index_pattern": "logs-*"
      }
    }
  ]
}

Verify

healops integrations verify opensearch

Expected output on success:

Service: opensearch
Status:  passed
Detail:  Connected to OpenSearch cluster 'my-cluster' (green, 3 node(s)).

How it works in investigations

When an OpenSearch integration is configured, HealOps automatically includes it as an evidence source during every investigation. Two tools become available to the investigation agent:

`query_elasticsearch_logs`

Searches log indices for messages matching a Lucene/KQL query within a bounded time window. The agent uses this to:

Pull error and exception messages around the alert timestamp
Filter logs by service, container, or correlation ID extracted from alert annotations
Surface stack traces and panic messages that explain a metric anomaly
Cross-reference logs against alerts firing in Datadog, Grafana, or Alertmanager

The tool returns both the raw matching logs and a separate error_logs slice pre-filtered for keywords like error, exception, traceback, and panic, so the agent can prioritize signal over noise.

`query_opensearch_analytics`

Runs bounded analytics queries against any index pattern (default *). The agent uses this for non-log data stored in OpenSearch — APM events, audit trails, business metrics, or any custom analytics index your team maintains. Both tools share the same configured credentials, so configuring the integration once enables both query paths.

Troubleshooting

Symptom	Fix
Status: missing	Set `OPENSEARCH_URL` or run `healops onboard` and pick OpenSearch
Connection refused	Verify the URL is reachable from this host; check firewall and VPC rules
401 Unauthorized	Verify credentials are correct. For self-hosted OpenSearch, use Basic Auth (`OPENSEARCH_USERNAME` + `OPENSEARCH_PASSWORD`), not API key — most installs do not have API keys enabled
SSL certificate errors	For self-signed certificates, ensure the CA cert is in the system trust store
Empty results from a known-good query	Confirm the index pattern matches your data; the default `` matches every index but specific patterns like `logs-` are faster and more reliable
`security_exception: no permissions`	The user needs at least `read` and `view_index_metadata` permissions on the queried indices

Security best practices

Create a read-only OpenSearch user for HealOps — the agent only reads logs and analytics indices and never writes to the cluster during investigations.
Limit the role to the indices HealOps needs (typically logs and APM indices), not cluster-wide.
Store credentials in .env or the integration store, not in source code.
For Elastic Cloud, generate a scoped API key and rotate it on a schedule rather than using the master deployment credentials.
For self-hosted clusters behind a reverse proxy, prefer Basic Auth over disabling security entirely — even on internal networks.

Overview

LLM providers

Observability and incidents

Cloud, code, and collaboration

Messaging

Data and workflow systems

Prerequisites

Setup

Option 1: Interactive onboarding wizard

Option 2: Legacy CLI

Option 3: Environment variables

Option 4: Persistent store

Verify

How it works in investigations

`query_elasticsearch_logs`

`query_opensearch_analytics`

Troubleshooting

Security best practices

​Prerequisites

​Setup

​Option 1: Interactive onboarding wizard

​Option 2: Legacy CLI

​Option 3: Environment variables

​Option 4: Persistent store

​Verify

​How it works in investigations

​query_elasticsearch_logs

​query_opensearch_analytics

​Troubleshooting

​Security best practices

Prerequisites

Setup

Option 1: Interactive onboarding wizard

Option 2: Legacy CLI

Option 3: Environment variables

Option 4: Persistent store

Verify

How it works in investigations

`query_elasticsearch_logs`

`query_opensearch_analytics`

Troubleshooting

Security best practices