Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Grafana Tempobreadcrumb arrow Configurebreadcrumb arrow 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:

  • OpenTelemetry Collector configuration
  • Grafana Alloy configuration
  • Any HTTP/gRPC client using curl or other relevant tools

Refer to Enable multi-tenancy for more information.