Tempo uses GitHub to manage reviews of pull requests:
- If you have a trivial fix or improvement, go ahead and create a pull request.
- If you plan to do something more involved, discuss your ideas on the relevant GitHub issue.
We use Go modules to manage dependencies on external packages. This requires a working Go environment with version 1.18 or greater and git 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]Before submitting please run the following to verify that all dependencies and proto defintions are consistent.
make vendor-checkAdditionally, this project uses gofumpt for code formatting. Contributors may wish to configure editors based on the gofumpt documentation, or alternatively run make fmt before committing changes for submission.
cmd/
tempo/ - main tempo binary
tempo-cli/ - cli tool for directly inspecting blocks in the backend
tempo-vulture/ - bird-themed consistency checker. optional.
tempo-query/ - jaeger-query GRPC plugin (Apache2 licensed)
tempo-serverless/ - serverless handler for searching backend storage for traces
docs/
example/ - great place to get started running Tempo
docker-compose/
tk/
integration/ - e2e tests
modules/ - top level Tempo components
compactor/
distributor/
ingester/
overrides/
querier/
frontend/
storage/
opentelemetry-proto/ - git submodule. necessary for proto vendoring
operations/ - Tempo deployment and monitoring resources (Apache2 licensed)
jsonnet/
tempo-mixin/
pkg/
tempopb/ - proto for interacting with various Tempo services (Apache2 licensed)
tempodb/ - object storage key/value database
vendor/
imports should follow std libs, externals libs and local packages format
Example
import (
"context"
"fmt"
"github.com/gogo/protobuf/proto"
"github.com/opentracing/opentracing-go"
"github.com/grafana/tempo/modules/overrides"
"github.com/grafana/tempo/pkg/validation"
)
- Metrics: Tempo is instrumented with Prometheus metrics. It emits RED metrics for most services and backends. The relevant dashboards can be found in the Tempo mixin.
- Logs: Tempo uses the go-kit level logging library and emits
logs in the
key=value(logfmt) format. - Traces: Tempo uses the Jaeger Golang SDK for tracing instrumentation. As of this writing, only the read path of tempo is instrumented for tracing.
We try to ensure that most functionality of Tempo is well tested.
- At the package level, we write unit tests that tests the functionality of the code in isolation.
These can be found within each package/module as
*_test.gofiles. - Next, a good practice is to use the examples provided and common tools like
docker-compose,tanka&helmto set up a local deployment and test the newly added functionality. - Finally, we write integration tests that often test the functionality of the ingest and query path of Tempo as a whole, including the newly introduced functionality. These can be found under the integration/e2e folder.
A CI job runs these tests on every PR.
Using a debugger can be useful to find errors in Tempo code. This example shows how to debug Tempo inside docker-compose.
Make sure to run
make lint
before submitting your PR to catch any linting errors. Linting can be fixed using
make fmt
However, do note that the above command requires the gofmt and goimports binaries accessible via $PATH.
If you have changed any jsonnet or libsonnet files, please run
make jsonnetfmt
This requires jsonnetfmt binary in $PATH.
To compile jsonnet files please run the following command
make jsonnet
This requires jsonnet, jsonnet-bundler and tanka binaries in $PATH.
Anyone can help with Tempo's documentation by writing new content, updating existing content, or creating an issue. Current documentation projects are tracked in GitHub issues. Browsing through issues is a good way to find something to work on.
Tempo documentation is located in the docs directory. The docs directory has three folders:
design-proposals: Used for project and feature proposals. This content is not published with the product documentation.internal: Used for internal process-related conteint, including diagrams.sources: All of the product documentation resides here.- The
helm-chartsfolder contains the documentation for thetempo-distributedHelm chart, https://grafana.com/docs/helm-charts/tempo-distributed/next/ - The
tempofolder contains the product documentation, https://grafana.com/docs/tempo/latest/
- The
Once you know what you would like to write, use the Writer's Toolkit for information on creating good documentation. The toolkit also provides document templates to help get started.
When you create a PR for documentation, add the type/doc label to identify the PR as contributing documentation.
If your content needs to be added to a previous release, use the backport label for the version. When your PR is merged, the backport label triggers an automatic process to create an additional PR to merge the content into the version's branch. Check the PR for content that might not be appropriate for the version. For example, if you fix a broken link on a page and then backport to Tempo 1.5, you would not want any TraceQL information to appear.
To preview the documentation locally, run make docs from the root folder of the Tempo repository. This uses
the grafana/docs image which internally uses Hugo to generate the static site. The site is available on localhost:3002/docs/.
Note The
make docscommand uses a lot of memory. If it is crashing, make sure to increase the memory allocated to Docker and try again.
Tempo uses a CI action to sync documentation to the Grafana website. The CI is
triggered on every merge to main in the docs subfolder.
The helm-charts folder is published from Tempo's next branch. The Tempo documentation is published from the latest branch.