OBSDOCS-3039: Tempo t-shirt size documentation

modules/distr-tracing-tempo-config-size.adoc

@@ -0,0 +1,293 @@
+// Module included in the following assemblies:
+//
+// * observability/distr_tracing/distr-tracing-tempo-configuring.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="distr-tracing-tempo-config-size_{context}"]
+= TempoStack deployment sizing
+
+Sizing for TempoStack follows the format of `1x.<size>` where the value `1x` is the number of instances and `<size>` specifies performance capabilities.
+
+[IMPORTANT]
+====
+It is not possible to change the number `1x` for the deployment size.
+====
+
+.TempoStack sizing
+[cols="1h,5*",options="header"]
+|===
+|
+|1x.demo
+|1x.pico
+|1x.extra-small
+|1x.small
+|1x.medium
+
+|Ingestion rate
+|Demo use only
+|Small workloads
+|100 GB/day
+|500 GB/day
+|2 TB/day
+
+|Replication factor
+|1
+|2
+|2
+|2
+|2
+
+|Total CPU requests
+|None
+|3.25 vCPUs
+|4.6 vCPUs
+|7.9 vCPUs
+|24 vCPUs
+
+|Total CPU requests if using the gateway
+|None
+|3.4 vCPUs
+|5.1 vCPUs
+|8.8 vCPUs
+|28.1 vCPUs
+
+|Total CPU requests if using the Jaeger UI
+|None
+|3.4 vCPUs
+|5.1 vCPUs
+|8.8 vCPUs
+|28.1 vCPUs
+
+|Total memory requests
+|None
+|8.8 Gi
+|22.1 Gi
+|30.1 Gi
+|47.1 Gi
+
+|Total memory requests if using the gateway
+|None
+|8.9 Gi
+|22.3 Gi
+|30.4 Gi
+|47.4 Gi
+
+|Total memory requests if using the Jaeger UI
+|None
+|8.9 Gi
+|22.3 Gi
+|30.4 Gi
+|47.4 Gi
+|===
+
+The `1x.demo` size is intended for demonstration and development purposes only. It has no resource constraints and a replication factor of 1, which means it does not provide high availability.
+
+For production deployments, use `1x.pico` or larger sizes which provide high availability with a replication factor of 2.
+
+The base resource totals include the following components: distributor, ingester, compactor, querier, and query frontend. The gateway component is optional and required for multi-tenant authentication; when enabled, it also deploys the gateway OPA sidecar. The Jaeger UI component is optional and provides the Jaeger query interface for trace visualization; when enabled, it also deploys the OAuth proxy for authentication.
+
+[id="distr-tracing-tempo-size-resources-per-component_{context}"]
+== Resource requests per component
+
+The following table shows the CPU and memory resource requests for each TempoStack component at each deployment size.
+
+.Resource requests per component
+[cols="2h,2*,2*,2*,2*,2*",options="header"]
+|===
+|Component
+2+|1x.pico
+2+|1x.extra-small
+2+|1x.small
+2+|1x.medium
+
+|
+|CPU
+|Memory
+|CPU
+|Memory
+|CPU
+|Memory
+|CPU
+|Memory
+
+|Distributor
+|500m
+|500 Mi
+|200m
+|128 Mi
+|600m
+|128 Mi
+|1500m
+|128 Mi
+
+|Ingester
+|500m
+|3 Gi
+|1500m
+|8 Gi
+|2000m
+|10 Gi
+|8000m
+|16 Gi
+
+|Compactor
+|500m
+|500 Mi
+|200m
+|4 Gi
+|400m
+|6 Gi
+|600m
+|10 Gi
+
+|Querier
+|750m
+|1536 Mi
+|1000m
+|1 Gi
+|2500m
+|3 Gi
+|5000m
+|4 Gi
+
+|Query frontend
+|500m
+|500 Mi
+|200m
+|1 Gi
+|400m
+|1 Gi
+|800m
+|1 Gi
+
+|Gateway
+|100m
+|64 Mi
+|400m
+|128 Mi
+|800m
+|192 Mi
+|4000m
+|192 Mi
+
+|Gateway OPA
+|50m
+|64 Mi
+|100m
+|64 Mi
+|100m
+|64 Mi
+|200m
+|128 Mi
+
+|Jaeger UI
+|100m
+|64 Mi
+|400m
+|128 Mi
+|800m
+|192 Mi
+|4000m
+|192 Mi
+
+|OAuth proxy
+|50m
+|64 Mi
+|100m
+|64 Mi
+|100m
+|64 Mi
+|200m
+|128 Mi
+|===
+
+[NOTE]
+====
+* Resource values listed are requests only. No resource limits are applied.
+* Ingester replicas are determined by the replication factor. For sizes with a replication factor of 2, multiply the ingester resources by 2 for the total ingester resource consumption.
+* The Gateway OPA sidecar is automatically deployed when the gateway is enabled.
+* The OAuth proxy is automatically deployed when the Jaeger UI is enabled.
+====
+
+[id="distr-tracing-tempo-size-cr-example_{context}"]
+== Configuring the size in a TempoStack CR
+
+You can configure the deployment size by setting the `spec.size` field in the TempoStack custom resource.
+
+.Example TempoStack CR with size configuration
+[source,yaml]
+----
+apiVersion: tempo.grafana.com/v1alpha1
+kind: TempoStack
+metadata:
+  name: example
+  namespace: tracing-system
+spec:
+  size: 1x.pico <1>
+  storageSize: 1Gi
+  storage:
+    secret:
+      name: object-storage-secret
+      type: s3
+  template:
+    queryFrontend:
+      jaegerQuery:
+        enabled: true
+----
+<1> Specifies the deployment size. Valid values are `1x.demo`, `1x.pico`, `1x.extra-small`, `1x.small`, and `1x.medium`.
+
+When you specify a size, the Operator automatically configures the resource requests for all TempoStack components and sets the appropriate replication factor. You do not need to manually configure individual component resources.
+
+[id="distr-tracing-tempo-size-resource-priority_{context}"]
+== Resource resolution priority
+
+When determining resources for a component, the Operator follows this priority order:
+
+. *Component override*: If `spec.template.<component>.resources` is set, use these values.
+. *Size profile*: If `spec.size` is set, use the t-shirt size profile values.
+. *Total resources*: If `spec.resources.total` is set, use the percentage-based split.
+. *No resources*: If none of the above are set, no resource requests are applied.
+
+This means that component-level overrides always take precedence, allowing you to customize specific components while using a t-shirt size as the baseline for the rest.
+
+[id="distr-tracing-tempo-size-customizing_{context}"]
+== Customizing component resources
+
+You can override resource requests for specific components while using a t-shirt size as the baseline. This is useful when a particular component in your deployment requires more or fewer resources than the default size profile provides.
+
+.Example TempoStack CR with component resource overrides
+[source,yaml]
+----
+apiVersion: tempo.grafana.com/v1alpha1
+kind: TempoStack
+metadata:
+  name: example
+  namespace: tracing-system
+spec:
+  size: 1x.small <1>
+  storageSize: 1Gi
+  storage:
+    secret:
+      name: object-storage-secret
+      type: s3
+  template:
+    ingester:
+      resources: <2>
+        requests:
+          cpu: 4
+          memory: 20Gi
+    querier:
+      replicas: 4 <3>
+    queryFrontend:
+      jaegerQuery:
+        enabled: true
+----
+<1> Sets the base size profile for all components.
+<2> Overrides the ingester resources. The ingester uses these explicit values instead of the `1x.small` defaults.
+<3> Configures the querier replicas. Replica counts are independent of the size profile.
+
+In this example:
+
+* The ingester uses the explicitly defined resources (4 CPU, 20Gi memory) instead of the `1x.small` defaults.
+* The querier uses 4 replicas with resources from the `1x.small` profile.
+* All other components (distributor, compactor, query frontend) use the `1x.small` default resources.

observability/distr_tracing/distr-tracing-tempo-configuring.adoc

@@ -22,6 +22,8 @@ include::modules/distr-tracing-tempo-config-default.adoc[leveloffset=+1]
 * xref:../../observability/distr_tracing/distr-tracing-tempo-installing.adoc#distr-tracing-tempo-installing[Installing a TempoStack instance]
 * xref:../../observability/distr_tracing/distr-tracing-tempo-installing.adoc#distr-tracing-tempo-installing[Installing a TempoMonolithic instance]
 
+include::modules/distr-tracing-tempo-config-size.adoc[leveloffset=+1]
+
 include::modules/distr-tracing-tempo-config-query-frontend.adoc[leveloffset=+1]
 
 [role="_additional-resources"]