M3 is an Apache-2.0 licensed, Go-based monorepo that provides a distributed time series database, query engine, metrics aggregator, and Prometheus sidecar for teams that need to store and query large volumes of metrics on their own infrastructure.

What it is

M3 is a monorepo written in Go that bundles several cooperating components into one project: a distributed time series database (M3DB), a query engine, a metrics aggregator, a Prometheus sidecar, and Graphite-compatible storage and query endpoints. It is documented at m3db.io and covers integrations with Prometheus, Graphite, and Kubernetes, which is where the project is meant to be operated. The repository carries an Apache-2.0 licence, 4,896 stars, 463 forks, and 222 open issues, with the most recent push recorded on 2026-09-18.

The concrete problem it solves is operating metrics storage at a scale where a single-node Prometheus instance stops being comfortable. It replaces the default local storage path of a Prometheus deployment by acting as a remote, distributed TSDB that Prometheus writes into through the sidecar and remote write, while still allowing PromQL-style querying through the query engine. It also gives Graphite users a compatible storage and query engine, so existing Graphite tooling can point at M3 instead of a Graphite backend. The aggregator handles rollups and downsampling so that retention policies and long-range queries do not have to be served from raw high-resolution data.

Key capabilities

• Distributed time series database (M3DB) with placements and namespaces configured over the HTTP API at POST /api/v1/database/create and POST /api/v1/services/m3db/namespace/ready.
• Query engine supporting range queries through POST /api/v1/query_range with query, start, end, and step parameters, including expressions such as third_avenue > 6000.
• JSON write endpoint at POST /api/v1/json/write accepting tagged metrics with __name__ and a timestamp and value pair.
• Prometheus sidecar integration so existing Prometheus deployments can use M3 as their storage layer.
• Graphite-compatible storage and query engine for teams with Graphite-format metrics and dashboards.
• Metrics aggregator component for aggregation and rollup workloads.
• Kubernetes-oriented deployment, with the administration API exposed on port 7201 and the data port on 7203.

Who uses it and how

• Platform and observability teams running Kubernetes that need metrics retention beyond what a single Prometheus server can hold.
• Teams migrating from Graphite that want to keep Graphite-compatible ingestion and query patterns while moving storage onto M3.
• Operators who need to define retention explicitly, for example a default namespace created with a retentionTime of 12h in a local test setup.
• Prometheus users who want a sidecar-based path to remote, distributed storage rather than federation or a hosted vendor.
• Environment where the deployment is Docker-based for evaluation, and per the README quickstart, a local placement type is used for a single-node trial.

Getting started

The README states that the simplest and quickest way to try M3 is Docker, following the M3 quickstart guide. The documented command runs docker run -p 7201:7201 -p 7203:7203 --name m3db -v $(pwd)/m3db_data:/var/lib/m3db quay.io/m3db/m3dbnode:v1.0.0, after which placement and namespace are created over the API and metrics are written and queried with curl.

How it compares

The provided facts name no commercial products that M3 replaces, and no directly comparable open-source tool is named either. On the evidence here, M3 stands alone in this registry as a combined distributed TSDB, aggregator, query engine, and Prometheus sidecar under a single Apache-2.0 licence.

When to use it — and when not to

The README is a quickstart rather than an operations manual, and it points outward to m3db.io for install options, dependencies, and reference material, so anyone running it in production should expect to lean on that external documentation. There are 222 open issues, and the excerpt does not spell out the database, object storage, or mail infrastructure a full deployment requires, which means the operating burden has to be assessed from the full documentation rather than the repository front page. Teams wanting a managed metrics backend with no operational surface, or those whose metric volume fits comfortably in a single Prometheus instance, are better served by not adopting M3.

docker run -p 7201:7201 -p 7203:7203 --name m3db -v $(pwd)/m3db_data:/var/lib/m3db quay.io/m3db/m3dbnode:v1.0.0

#!/bin/bash
curl -X POST http://localhost:7201/api/v1/database/create -d '{
  "type": "local",
  "namespaceName": "default",
  "retentionTime": "12h"
}' | jq .

curl -X POST http://localhost:7201/api/v1/services/m3db/namespace/ready -d '{
  "name": "default"
}' | jq .

#!/bin/bash
curl -X POST http://localhost:7201/api/v1/json/write -d '{
  "tags": 
    {
      "__name__": "third_avenue",
      "city": "new_york",
      "checkout": "1"
    },
    "timestamp": '\"$(date "+%s")\"',
    "value": 3347.26
}'

curl -X "POST" -G "http://localhost:7201/api/v1/query_range" \
  -d "query=third_avenue" \
  -d "start=$(date "+%s" -d "45 seconds ago")" \
  -d "end=$( date +%s )" \
  -d "step=5s" | jq .  

curl -X "POST" -G "http://localhost:7201/api/v1/query_range" \
  -d "query=third_avenue > 6000" \
  -d "start=$(date -v -45S "+%s")" \
  -d "end=$( date +%s )" \
  -d "step=5s" | jq .