Elasticsearch Integration

Prerequisites

  • Middleware Host Agent installed on the machine that will collect metrics. See the Installation Guide.
  • Elastic superuser privileges to allow stats access. Elastic provides a built-in superuser role and an elastic superuser account; follow Elastic guidance to create users/roles with the minimum necessary privileges.

Setup

1 Create database credentials

Create a YAML file with your Elasticsearch endpoint and (if enabled) credentials. If your cluster is not password-protected, omit username and password. Example: /home/ubuntu/elasticsearch-creds.yaml

1elasticsearch:
2  endpoint: http://localhost:9200
3  username: YOUR_USERNAME
4  password: YOUR_PASSWORD

Docker Agent: place the YAML inside /var/log on the Agent host. Docker Agents might not support dynamic volume binding. Quick verify (from the Agent host):

1# If auth is enabled, add: -u USER:PASS
2curl -s http://<es-host>:9200/_cluster/health?pretty
3curl -s http://<es-host>:9200/_nodes/stats?filter_path=nodes.*.jvm,cluster_name | head

These endpoints confirm reachability/permissions and return cluster health and node statistics.

2 Access Integrations

In Middleware, go to Installations → All Integrations → Elasticsearch (the original page mistakenly references MySQL—use Elasticsearch here).

Elasticsearch Overview

3 Enable Integration

Select the host (where the Host Agent is running), provide the credential file path from Step 1, and Save.

Elasticsearch Enable

Visualize Your Data

  • Default Elasticsearch dashboard: Open Dashboard Builder → Elasticsearch – Metrics (Runtime) for ready-to-use graphs.
  • Create widgets: In a dashboard, choose Add New Widget → elasticsearch to build custom charts (e.g., disk I/O per node, CPU, JVM heap, shard sizes, indexing pressure).

Alerts

Create alerts on any Elasticsearch metric. Choose Database as the detection method and Elasticsearch as the database type; pick a metric and set conditions (e.g., high indexing_pressure, low disk available, rising thread_pool.tasks.queued).

Metrics Collected

MetricDescription
elasticsearch.breaker.memory.estimatedEstimated memory used for the operation
elasticsearch.breaker.memory.limitMemory limit for circuit breaker
elasticsearch.breaker.trippedNumber of times the circuit breaker prevented an OOM.
elasticsearch.node.cache.memory.usageCache size in bytes on a node.
elasticsearch.node.cache.evictionsCache evictions on a node.
elasticsearch.node.cache.countTotal query cache misses across shards on selected nodes.
elasticsearch.node.fs.disk.availableDisk space available to the JVM across all file stores.
elasticsearch.node.fs.disk.freeUnallocated disk space across all file stores.
elasticsearch.node.fs.disk.totalTotal disk space across all file stores.
elasticsearch.node.disk.io.readTotal KB read across file stores (per node).
elasticsearch.node.disk.io.writeTotal KB written across file stores (per node).
elasticsearch.node.cluster.ioBytes sent/received for internal cluster communication.
elasticsearch.node.cluster.connectionsOpen TCP connections for internal cluster comms.
elasticsearch.node.http.connectionsHTTP connections to the node.
elasticsearch.node.operations.completedOperations completed by a node.
elasticsearch.node.operations.timeTime spent on operations by a node.
elasticsearch.node.shards.sizeSize of shards assigned to this node
elasticsearch.node.shards.data_set.sizeTotal data set size of shards on this node.
elasticsearch.node.shards.reserved.sizePredicted growth of shard stores on this node.
elasticsearch.node.translog.operationsTransaction log operations.
elasticsearch.node.translog.sizeTransaction log size.
elasticsearch.node.translog.uncommitted.sizeUncommitted translog size.
elasticsearch.node.thread_pool.threadsThreads in the thread pool.
elasticsearch.node.thread_pool.tasks.queuedQueued tasks in the thread pool.
elasticsearch.node.thread_pool.tasks.finishedTasks finished by the thread pool.
elasticsearch.node.documentsDocuments on the node.
elasticsearch.node.open_filesOpen file descriptors held by the node.
jvm.classes.loadedLoaded JVM classes.
jvm.gc.collections.countTotal garbage collections.
jvm.gc.collections.elapsedAccumulated GC time.
jvm.memory.heap.maxMax heap memory
jvm.memory.heap.usedCurrent heap usage.
jvm.memory.heap.committedCommitted heap memory.
jvm.memory.nonheap.usedCurrent non-heap memory usage
jvm.memory.nonheap.committedAmount of memory that is guaranteed to be available for non-heap purposes
jvm.memory.pool.maxMaximum amount of memory can be used for the memory pool
jvm.memory.pool.usedCurrent memory pool memory usage
jvm.threads.countCurrent number of threads
elasticsearch.cluster.pending_tasksNumber of cluster-level changes that have not yet been executed
elasticsearch.cluster.in_flight_fetchNumber of unfinished fetches
elasticsearch.cluster.shardsNumber of shards in the cluster
elasticsearch.cluster.data_nodesNumber of data nodes in the cluster
elasticsearch.cluster.nodesTotal number of nodes in the cluster
elasticsearch.cluster.healthThe health status of the cluster
elasticsearch.os.cpu.usageRecent CPU usage for the whole system, or -1 if not supported
elasticsearch.os.cpu.load_avg.1m1-minute system load average.
elasticsearch.os.cpu.load_avg.5m5-minute system load average.
elasticsearch.os.cpu.load_avg.15m15-minute system load average.
elasticsearch.os.memoryPhysical memory amount.
elasticsearch.memory.indexing_pressureBytes consumed by indexing requests (stage-specific).
elasticsearch.indexing_pressure.memory.total.primary_rejectionsCumulative primary-stage indexing rejections.
elasticsearch.indexing_pressure.memory.total.replica_rejectionsReplica-stage indexing rejections.
elasticsearch.indexing_pressure.memory.limitConfigured memory limit, in bytes, for the indexing requests
elasticsearch.cluster.state_queueNumber of cluster states in queue
elasticsearch.cluster.published_states.fullNumber of published cluster states
elasticsearch.cluster.published_states.differencesNumber of differences between published cluster states
elasticsearch.cluster.state_update.countCluster state updates that changed state.
elasticsearch.cluster.state_update.timeTime spent updating cluster state.
elasticsearch.cluster.indices.cache.evictionsNumber of evictions from the cache for indices in the cluster
elasticsearch.node.ingest.documentsTotal documents ingested during the lifetime of this node
elasticsearch.node.ingest.documents.currentTotal documents currently being ingested
elasticsearch.node.ingest.operations.failedTotal failed ingest operations during the lifetime of this node
elasticsearch.node.pipeline.ingest.documents.preprocessedNumber of documents preprocessed by the ingest pipeline
elasticsearch.node.pipeline.ingest.operations.failedTotal failed operations for the ingest pipeline
elasticsearch.node.pipeline.ingest.documents.currentTotal documents currently being ingested by a pipeline
elasticsearch.node.script.compilationsTotal inline script compilations performed by the node
elasticsearch.node.script.cache_evictionsTotal times the script cache has evicted old data
elasticsearch.node.script.compilation_limit_triggeredTimes script compile circuit breaker limited compilations.
elasticsearch.node.segments.memorySize of memory for segment object of a node
elasticsearch.index.operations.completedNumber of operations completed for an index
elasticsearch.index.operations.timeTime spent on operations for an index
elasticsearch.index.shards.sizeSize of the shards assigned to this index
elasticsearch.process.cpu.usageCPU usage in percent
elasticsearch.node.operations.currentNumber of query operations currently running
elasticsearch.index.documentsNumber of documents for an index
elasticsearch.process.memory.virtualJVM process virtual memory size.
elasticsearch.process.cpu.timeJVM process CPU time.

Troubleshooting

Integrations menu is missing

  • Your user likely lacks Installation permissions. Ask an admin to grant the Installation permission in Settings.

Endpoint unreachable from the Host Agent From the Agent host, run:

1curl -s http://<es-host>:9200/_cluster/health?pretty
  • If this fails, fix DNS/firewall/routing or use the correct scheme/port (e.g., https:// behind proxies or Elastic Cloud). The health API should return a JSON status (green/yellow/red).

Authentication/authorization errors (401/403)

  • Confirm the YAML creds are correct and have sufficient privileges. Elastic’s superuser role has full access, but Elastic recommends creating narrowly-scoped roles where possible.

To verify what your user can do, call:

1curl -s -u USER:PASS http://<es-host>:9200/_security/user/_privileges
  • (Returns the logged-in user’s privileges.)

Docker Agent can’t read the credentials file

  • Ensure the file is inside /var/log on the Agent host when using the Middleware Docker Agent (dynamic volume binding may not be supported). Update the integration to point to that path.

Metrics look partial or stale Check the _nodes/stats endpoint directly to ensure the cluster is returning JVM/OS/thread pool stats:

1curl -s http://<es-host>:9200/_nodes/stats?filter_path=nodes.*.os,nodes.*.jvm,nodes.*.thread_pool | head
  • If output is limited, review your user’s privileges or cluster settings.

Need assistance or want to learn more about Middleware? Contact our support team at [email protected] or join our Slack channel.