This is documentation for the next version of Grafana Tempo documentation. For the latest stable release, go to the latest version.

Configure

Tenant IDs

Open source

Tenant IDs

Within a Grafana Tempo cluster, the tenant ID is the unique identifier of a tenant. Tenant IDs enable multi-tenancy in Tempo, allowing multiple organizations or tenants to share the same Tempo cluster while maintaining data isolation.

Tempo uses the X-Scope-OrgID HTTP header to identify and enforce tenant boundaries. This header is set to the tenant ID value and is used for:

Scoped writes (ingest): Each span is stored under its specified tenant, ensuring data isolation at the storage level
Scoped reads (queries): Queries return only data belonging to the specified tenant

For more information about setting up multi-tenancy, refer to Enable multi-tenancy.

Characters and length restrictions

Tenant IDs must be less-than or equal-to 150 bytes in length. The length is measured in bytes, not characters, which is important for multi-byte characters.

Tenant IDs can only include the following supported characters:

Alphanumeric characters (0-9, a-z, A-Z)
Special characters (!, -, _, ., *, ', (, ))

All other characters, including slashes (/), backslashes (\), and whitespace, aren’t supported.

Tenant IDs are case-sensitive. For example, Tenant-123 and tenant-123 are treated as different tenant IDs.

The tenant ID should not be empty.

For security reasons, . and .. aren’t valid tenant IDs. These values are restricted to prevent path traversal attacks.

Cross-tenant queries

Cross-tenant queries are supported for search, search-tags, and trace-by-ID search operations. Refer to Cross-tenant query federation for more information.

Multitenancy

Tenant IDs are transmitted to Tempo via the X-Scope-OrgID HTTP header. This header must be included in all requests to Tempo when multi-tenancy is enabled.

Multi-tenancy on ingestion is supported with both gRPC and HTTP for OTLP (OpenTelemetry Protocol). You can add the header in: