FAQ

The wizard only writes config.yaml. To start sending data, you must actually run the agent:

    ./agent --config config.yaml

The cluster appears within a few seconds of the first heartbeat. Check agent.log if it doesn't appear.

This means OpenSearch is using a self-signed or internal CA certificate. Fix options:

1. Quickest: set tls_skip_verify: true in config.yaml (not recommended for production).
2. Better: set ca_cert_path to your CA certificate file (PEM format):
   ca_cert_path: "/etc/ssl/certs/my-ca.pem"

The --init wizard asks about this in step 3 (SSL/TLS verification).

Create a dedicated read-only role:

PUT _plugins/_security/api/roles/osd_agent
{
  "cluster_permissions": [
    "cluster:monitor/*",
    "cluster:admin/snapshot/get",
    "cluster:admin/repository/get",
    "indices:admin/template/get",
    "indices:monitor/*"
  ],
  "index_permissions": [{
    "index_patterns": ["*"],
    "allowed_actions": ["indices:monitor/*", "indices:admin/settings/get"]
  }]
}

For security diagnostics to work, also add:
"cluster:admin/opendistro/security/ssl/certs/info"

Then map a user to that role and use that user in config.yaml.

Possibly yes. A green cluster with no resource pressure, no unassigned shards, recent snapshots, and TLS enabled should produce zero findings.

If you expect findings that aren't there, run the agent in test mode to see exactly what was collected:

./agent --config config.yaml --test

This prints a local summary without sending to the platform.

The agent is marked offline if no heartbeat is received for 30 minutes.

Check:
1. Is the agent process still running? (systemctl status opensearch-doctor-agent or pgrep agent)
2. Can the server reach opensearchdoctor.com on port 443? (curl -I https://opensearchdoctor.com)
3. Check agent.log for connection errors.
4. If using a firewall, allow outbound HTTPS to opensearchdoctor.com.

Yes. Run a separate agent instance for each cluster, each with its own config.yaml and api_key.

The number of clusters you can connect depends on your plan:
- Free: 1 cluster
- Starter: 3 clusters
- Pro: 10 clusters
- Scale: unlimited

Each cluster needs its own agent key (Settings → Agent Keys in the dashboard).

No. The agent never calls _search, _get, or any endpoint that returns document content.

It only reads:
- Cluster-level metrics (health, node stats, shard counts)
- Index-level metadata (names, shard counts, sizes, settings)
- Plugin list, ISM policy names, ingest pipeline names, template names

No document data, no field values, no query content ever leaves your network.
You can verify this by reading the source: internal/collector/collect.go lists every API call made.

Yes. The agent's target URL is configurable:

saas:
  api_url: "https://your-instance.example.com"

Or via environment variable:
OPENSEARCH_DOCTOR_URL=https://your-instance.example.com ./agent --config config.yaml

The backend source code is not currently public, but the agent is open source and the API contract is documented.

Data retention depends on your plan:
- Free: 7 days
- Starter: 30 days
- Pro: 90 days
- Scale: 180 days

Data older than your retention window is automatically deleted by a nightly job. If you cancel your subscription, your data is retained for 30 days before being purged.

Yes. The agent is open source (Apache 2.0):

git clone https://github.com/opensearch-doctor/agent
cd agent
go build -o agent ./cmd/agent

Requires Go 1.22+. Run go vet ./... and go test ./... to verify.