Monitoring

Monitoring applications and databases is essential to track the load and resources used by the system.

Memgraph currently supports:

1. Real-time logs tracking via WebSocket server: Log tracking is helpful for debugging purposes and monitoring the database operations.
2. Metrics tracking via HTTP server (Enterprise Edition): In the Enterprise edition, besides log tracking, Memgraph allows tracking information about transactions, query latencies, types of queries executed, snapshot recovery latencies, triggers, TTL data, Bolt messages, indexes, streams, memory, operators and sessions. There are also many metrics which are trying to describe the state of high availability. These include metrics which describe latencies of RPC messages, time needed to perform a failover and counters for events occurring throughout the lifetime of HA Memgraph.
3. Session trace: Profile the execution of all queries within a session to identify performance bottlenecks.

Real-time logs tracking via WebSocket server

Connect to Memgraph’s logging server via WebSocket to forward logs to all the connected clients.

Log messages

Each log that is written to the log file is forwarded to the connected clients in the following format:

{
  event: "log",
  level: "trace"|"debug"|"info"|"warning"|"error"|"critical",
  message: "<log-message>"
}

Connection

To connect to Memgraph’s WebSocket server, use the following URL:

ws://host:port

The default host is 0.0.0.0, but it can be changed using the --monitoring-address= configuration flag.

The default port is 7444, but it can be changed using the --monitoring-port configuration flag.

To connect to Memgraph’s WebSocket server using the default configuration and Python client, you can use the following code snippet:

import asyncio
import websockets
 
HOST = 'localhost'
PORT = '7444'
 
# The WebSocket URL
ws_url = f'ws://{HOST}:{PORT}'
 
async def read_logs():
    async with websockets.connect(ws_url) as websocket:
        print(f"Connected to Memgraph at {ws_url}")
        try:
            # Keep reading messages (logs) from the server
            while True:
 log_message = await websocket.recv()
                print(log_message)
        except websockets.exceptions.ConnectionClosed:
            print("Connection to Memgraph closed.")
 
asyncio.run(read_logs())

The code structure is similar in other languages, depending on the WebSocket library used.

If you want to connect with a WebSocket Secure (WSS) connection, set the --bolt-cert-file and --bolt-key-file configuration flags to enable an SSL connection. Refer to the configuration page to learn how to update the configuration and to see the list of all available configuration flags.

Authentication

When authentication is not used due to no users present in Memgraph, no authentication message is expected, and no response will be returned.

When the authentication is used, Memgraph won’t send a message to a certain connection until it’s authenticated.

To authenticate, create a JSON with the credentials in the following format:

{
  "username": "<username>",
  "password": "<password>"
}

If the credentials are valid, the connection will be made, and the client will receive the messages. As a response, the client should receive the following message:

{
  "success": true,
  "message": "User has been successfully authenticated!"
}

If they are invalid or the first message is in an invalid format, the connection is dropped. As a response, the following message is sent:

{
  "success": false,
  "message": "<error-message>"
}

To use WebSocket to authenticate, send the JSON message to the WebSocket server:

import asyncio
import json
import websockets
 
HOST = "localhost"
PORT = "7444"
USERNAME = "memgraph"
PASSWORD = "memgraph"
 
ws_url = f"ws://{HOST}:{PORT}"
 
 
async def authenticate_and_read_logs(websocket):
    # Send authentication credentials
    credentials = json.dumps({"username": USERNAME, "password": PASSWORD})
    await websocket.send(credentials)
 
    # Wait for authentication response
    response = await websocket.recv()
    response_data = json.loads(response)
    if response_data.get("success"):
        print("Authentication successful!")
    else:
        print(f"Authentication failed: {response_data.get('message')}")
        return  # Stop if authentication fails
 
    # After successful authentication, start reading logs
    try:
        while True:
            log_message = await websocket.recv()
            print(log_message)
    except websockets.exceptions.ConnectionClosed:
        print("Connection to Memgraph closed.")
 
 
async def connect_and_authenticate():
    async with websockets.connect(ws_url) as websocket:
        print(f"Connected to Memgraph at {ws_url}")
        await authenticate_and_read_logs(websocket)
 
 
asyncio.run(connect_and_authenticate())

Authorization (Enterprise)

Permission for connecting through WebSocket is controlled by the WEBSOCKET privilege.

Metrics tracking via HTTP server (Enterprise Edition)

In the Enterprise Edition, Memgraph allows tracking information about high availability, transactions, query latencies, snapshot recovery latencies, triggers, Bolt messages, indexes, constraints, streams, memory, operators and sessions, all by using an HTTP server.

To retrieve data from the HTTP server, enter a valid Memgraph Enterprise license key.

The default address and port for the metrics server is 0.0.0.0:9091, and can be configured using the --metrics-address and --metrics-port configuration flags.

Metrics format

The --metrics-format configuration flag controls the response format of the HTTP endpoint. The allowed values are:

• OpenMetrics: Prometheus-compatible OpenMetrics text format (application/openmetrics-text). Metrics are labeled per-database. Any OpenMetrics compatible clients can connect directly to Memgraph to scrape metrics.
• JSON (default): A flat JSON object. The JSON format is deprecated. Using JSON with any OpenMetrics compatible client requires the Prometheus exporter middleware.

New deployments should use OpenMetrics, which enables direct Prometheus scraping and provides per-database metric labels.

Per-database metrics

Most metrics are tracked per-database. In a multi-tenant setup, each database maintains its own counters, gauges, and histograms. How per-database metrics are exposed depends on the format — see the OpenMetrics and JSON sections below.

Session-related metrics (active sessions, Bolt messages) and high-availability metrics remain global — they are not scoped to any single database.

System metrics

All system metrics measuring different parts of the system can be divided into three different types:

• Gauge — a single value of some variable in the system (e.g. memory usage, active transaction count)
• Counter — a monotonically increasing value (e.g. total number of committed transactions)
• Histogram — distribution of measured values (e.g. query latency percentiles)

General metrics

Index metrics

Constraint metrics

Memory metrics

Operator metrics

Before a Cypher query is executed, it is converted into an internal form suitable for execution, known as a query plan. A query plan is a tree-like data structure describing a pipeline of operations that will be performed on the database in order to yield the results for a given query. Every node within a plan is known as a logical operator and describes a particular operation.

All operator metrics are counters tracking how many times each operator was used.

Query metrics

Schema and storage info metrics

Session metrics

Session metrics are global; they are not scoped to any individual database.

Snapshot metrics

Stream metrics

Transaction metrics

Trigger metrics

TTL metrics

HA metrics

HA metrics are global; they are not scoped to any individual database.

Latency histograms

Throughput histograms

Throughput metrics are labeled per replica with an mg_instance label.

Counters

OpenMetrics monitoring

Set --metrics-format=OpenMetrics to enable the OpenMetrics endpoint. The response uses OpenMetrics text format (application/openmetrics-text), which any Prometheus-compatible client can scrape directly.

The metrics are served at http://host:port/metrics (or http://host:port/). See Prometheus scrape configuration for how to set up scraping.

Per-database labels

Per-database metrics carry database and uuid labels identifying which database they belong to. Global metrics (such as sessions, HA) have no database label.

# TYPE memgraph_vertex_count gauge
memgraph_vertex_count{database="memgraph",uuid="abc-123"} 42254
memgraph_vertex_count{database="analytics",uuid="def-456"} 1000
# TYPE memgraph_active_sessions gauge
memgraph_active_sessions 3

Instance status gauges

The following per-instance gauges are exposed for each registered HA instance. Each metric carries an mg_instance label identifying the instance by name.

All instances expose instance_up and instance_last_response_seconds. Coordinator instances additionally expose instance_is_leader, while data instances expose instance_is_main.

Prometheus scrape configuration

Add Memgraph as a scrape target in your prometheus.yml:

scrape_configs:
  - job_name: "memgraph"
    metrics_path: "/metrics"
    static_configs:
      - targets: ["memgraph-host:9091"]

JSON monitoring (deprecated)

Set --metrics-format=JSON (the current default) to enable the JSON endpoint. This format is deprecated and will be removed in a future release.

To retrieve the metrics, send a GET request to http://host:port/metrics or http://host:port/:

import json
import requests
 
 
def fetch_memgraph_metrics():
    metrics_url = "http://0.0.0.0:9091/metrics"
 
    try:
        response = requests.get(metrics_url, timeout=5)
 
        if response.status_code == 200:
            metrics_data = json.loads(response.text)
            print("Memgraph Metrics:\n", json.dumps(metrics_data, indent=4))
        else:
            print(f"Failed to fetch metrics. Status code: {response.status_code}")
    except requests.exceptions.RequestException as e:
        print(f"An error occurred: {e}")
 
 
fetch_memgraph_metrics()

Response format

The endpoint returns a JSON object grouped by metric category. Each category contains key-value pairs of metric names and their values:

{
  "General": {
    "vertex_count": 42254,
    "edge_count": 871978,
    "average_degree": 41.2732,
    "disk_usage": 81508835,
    "memory_usage": 339640320,
    "peak_memory_usage": 339775488,
    "unreleased_delta_objects": 0,
    "SocketConnect_us_50p": 0,
    "SocketConnect_us_90p": 0,
    "SocketConnect_us_99p": 0
  },
  "Index": {
    "ActiveLabelIndices": 6,
    "ActiveLabelPropertyIndices": 18
  },
  "Transaction": {
    "ActiveTransactions": 1,
    "CommitedTransactions": 0,
    "RollbackedTransactions": 0
  }
}

Metric naming

The JSON endpoint uses different metric names from the OpenMetrics tables above, and groups metrics into categories. Histogram values are reported in microseconds with _us_50p, _us_90p, _us_99p suffixes rather than as native Prometheus histograms in seconds.

Some notable name differences:

The full set of JSON names can be seen in the SHOW METRICS INFO output documented on the server stats page.

Aggregated metrics

The JSON format aggregates per-database metrics into global totals; it does not expose per-database breakdowns. For per-database visibility, use --metrics-format=OpenMetrics or the SHOW METRICS INFO Cypher query.

HA counter reset behaviour

All HA metrics with type Counter are aggregated for all coordinators. That makes it easier for users to track what is going on since they don’t need to aggregate by their own metrics specific to each coordinators. Also, after every pull, HA metrics with type Counter are in Memgraph reset to 0. This makes it possible to use Gauge on the client side without worrying that on restart we will lose all data.

The ReplicaRecoverySuccess, ReplicaRecoveryFail, and ReplicaRecoverySkip counters are excluded from this behaviour and report cumulative totals.

mg-exporter

OpenMetrics compatible clients cannot scrape the JSON endpoint directly. Use the separate Prometheus exporter middleware, which reads the JSON endpoint and re-exposes metrics in a Prometheus-compatible format.

Migrating from JSON to OpenMetrics

If you are currently using the deprecated JSON metrics endpoint, follow these steps to switch to OpenMetrics.

Configuration change

Set --metrics-format=OpenMetrics instead of JSON. The endpoint address and port remain the same.

If you were using mg-exporter to bridge the JSON endpoint to Prometheus, you can remove it: Prometheus can now scrape the OpenMetrics endpoint directly.

Metric name changes

OpenMetrics uses memgraph_ prefixed, snake_case names (e.g. memgraph_vertex_count) instead of the JSON CamelCase names (e.g. vertex_count). See the metric naming table in the JSON section for a summary of notable differences. You will need to update any dashboard queries or alerting rules that reference the old names.

Histogram format change

JSON reported histograms as three fixed percentile values in microseconds with _us_50p, _us_90p, _us_99p suffixes. OpenMetrics exposes native Prometheus histograms in seconds with configurable bucket boundaries. Update any dashboard panels that reference histogram metrics to use Prometheus histogram_quantile() functions and adjust for the unit change.

Per-database labels

The JSON endpoint aggregated all database metrics into global totals. The OpenMetrics endpoint exposes metrics per database, using database and uuid labels. Existing dashboard queries that expect flat, unlabelled metrics will need to be updated — either by filtering on a specific database label or by aggregating with sum().

HA counter semantics

In the JSON endpoint, most HA counter metrics use delta semantics: they reset to zero after each scrape. In OpenMetrics, all counters are cumulative (as per the Prometheus data model). If your alerting rules relied on the delta behaviour, switch to using rate() or increase() functions in your queries.

New metrics

The OpenMetrics endpoint exposes instance status gauges for each registered HA instance (e.g. memgraph_instance_is_alive, memgraph_instance_is_main). These are not available in the JSON format.

Session trace

A session refers to a temporary, interactive connection from a client (either a user or an application) to the database server, used to execute a series of transactions and queries. Session trace is a feature in Memgraph that allows you to profile the execution of all queries within a session, providing detailed information on query parsing, planning and execution. This can be invaluable for understanding performance bottlenecks and optimizing database interactions.

Session trace events are emitted into the main Memgraph log at the INFO level, tagged with the session that produced them. There is no separate per-session log file — every traced session interleaves into the same log stream and is told apart by its [session=<uuid>] tag.

Enabling session trace

Enable session trace for your current session using the following command:

SET SESSION TRACE ON;

The command returns the unique UUID of the session being traced:

Use this UUID to find the session’s events in the log. From this point on, every query executed in the session emits tagged trace events until tracing is turned off.

Reading the trace

Each trace event is a line in the main log prefixed with the session tag, the user (when authenticated) and the current transaction id:

[session=<uuid>] [user=<user>] [tx=<id>] <event>

To isolate a single session’s trace, filter the main log by its UUID:

grep -F '[session=de9c907b-6675-40bd-bf09-d4ce7b24f22d]' /var/log/memgraph/<memgraph_date>.log

The trace captures detailed information for every query executed during the session, including:

• Session UUID, user and transaction ID: carried on every tagged line.
• Accepted query: the query text as received.
• Parsing, planning and execution timings: start and end markers and durations for each phase.
• Explain and profile plans: the query’s plan and, after execution, its profiling statistics and execution counters.
• Commit timings: start and end markers for the commit phase.
• Failed queries: the error message when a query throws.

This detailed logging helps in profiling the entire session workload, increasing visibility into potential performance bottlenecks without enabling trace-level logging globally.

Disabling session trace

To stop emitting trace events for the current session, use the following command:

SET SESSION TRACE OFF;

After executing this command, no further trace events are written for the active session.