Cortex is a CNCF sandbox project used in several production systems including Weave Cloud, GrafanaCloud and FreshTracks.io.
Cortex provides horizontally scalable, multi-tenant, long term storage for Prometheus metrics when used as a remote write destination, and a horizontally scalable, Prometheus-compatible query API.
Multi-tenant means it handles metrics from multiple independent Prometheus sources, keeping them separate.
Instrumenting Your App: Best Practices
There are several commercial services where you can use Cortex on-demand:
Weave Cloud from Weaveworks lets you deploy, manage, and monitor container-based applications. Sign up at https://cloud.weave.works and follow the instructions there. Additional help can also be found in the Weave Cloud documentation.
To use Cortex as part of Grafana Cloud, sign up for GrafanaCloud by clicking "Log In" in the top right and then "Sign Up Now". Cortex is included as part of the Starter and Basic Hosted Grafana plans.
For a guide to contributing to Cortex, see the contributor guidelines.
To build:
make
(By default, the build runs in a Docker container, using an image built
with all the tools required. The source code is mounted from where you
run make into the build container as a Docker volume.)
To run the test suite:
make test
First, start minikube.
You may need to load the Docker images into your minikube environment. There is a convenience rule in the Makefile to do this:
make prime-minikube
Then run Cortex in minikube:
kubectl apply -f ./k8s
(these manifests use latest tags, i.e. this will work if you have
just built the images and they are available on the node(s) in your
Kubernetes cluster)
Cortex will sit behind an nginx instance exposed on port 30080. A job is deployed to scrape itself. Try it:
http://192.168.99.100:30080/api/prom/api/v1/query?query=up
If that doesn't work, your Minikube might be using a different ip address. Check with minikube status.
We uses Go modules to manage dependencies on external packages. This requires a working Go environment with version 1.11 or greater, git and bzr installed.
To add or update a new dependency, use the go get command:
# Pick the latest tagged release.
go get example.com/some/module/pkg
# Pick a specific version.
go get example.com/some/module/[email protected]Tidy up the go.mod and go.sum files:
go mod tidy
git add go.mod go.sum
git commitYou have to commit the changes to go.mod and go.sum before submitting the pull request.
To learn more about Cortex, consult the following documents/talks:
- Original design document for Project Frankenstein
- PromCon 2016 Talk: "Project Frankenstein: Multitenant, Scale-Out Prometheus": video, slides
- KubeCon Prometheus Day talk "Weave Cortex: Multi-tenant, horizontally scalable Prometheus as a Service" slides
- CNCF TOC Presentation; "Horizontally Scalable, Multi-tenant Prometheus" slides
If you have any questions about Cortex:
- Ask a question on the Cortex Slack channel. To invite yourself to the CNCF Slack, visit http://slack.cncf.io/.
- File an issue.
- Send an email to [email protected]
Your feedback is always welcome.