[DOC] Update Tempo doc to Alloy (#3843)

docs/sources/tempo/configuration/grafana-agent/_index.md

@@ -14,6 +14,12 @@ aliases:
 collector for sending metrics, logs, and trace data to the opinionated
 Grafana observability stack.
 
+{{< admonition type="note">}}
+Grafana Alloy provides tooling to convert your Agent Static or Flow configuration files into a format that can be used by Alloy.
+
+For more information, refer to [Migrate to Alloy](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/migrate-alloy).
+{{< /admonition>}}
+
 It's commonly used as a tracing pipeline, offloading traces from the
 application and forwarding them to a storage backend.
 Grafana Agent tracing stack is built using OpenTelemetry.

docs/sources/tempo/configuration/grafana-agent/automatic-logging.md

@@ -9,6 +9,8 @@ aliases:
 
 # Automatic logging: Trace discovery through logs
 
+{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+
 Running instrumented distributed systems is a very powerful way to gain
 understanding over a system, but it brings its own challenges. One of them is
 discovering which traces exist.
@@ -19,15 +21,15 @@ Automatic logging provides an easy and fast way of discovering trace IDs
 through log messages. Well-formatted log lines are written to a Loki instance
 or to `stdout` for each span, root, or process that passes through the tracing
 pipeline. This allows for automatically building a mechanism for trace
-discovery. On top of that, we also get metrics from traces using Loki, and
+discovery. On top of that, you can also get metrics from traces using Loki, and
 allow quickly jumping from a log message to the trace view in Grafana.
 
-While this approach is useful, it isn't as powerful as [TraceQL]({{< relref
-"../../traceql" >}}). If you are here because you know you want to log the
+While this approach is useful, it isn't as powerful as TraceQL.
+If you are here because you know you want to log the
 trace ID, to enable jumping from logs to traces, then read on!
 
 If you want to query the system directly, read the [TraceQL
-documentation]({{< relref "../../traceql" >}}). 
+documentation](https://grafana.com/docs/tempo/<TEMPO_VERSION>/traceql).
 
 ## Configuration
 
@@ -41,11 +43,17 @@ This allows searching by those key-value pairs in Loki.
 
 ## Before you begin
 
+{{< admonition type="note">}}
+Grafana Alloy provides tooling to convert your Agent Static or Flow configuration files into a format that can be used by Alloy.
+
+For more information, refer to [Migrate to Alloy](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/migrate-alloy).
+{{< /admonition>}}
+
 To configure automatic logging, you need to select your preferred backend and the trace data to log.
 
-To see all the available config options, refer to the [configuration reference](/docs/agent/latest/configuration/traces-config).
+To see all the available configuration options, refer to the [configuration reference](https://grafana.com/docs/agent/latest/configuration/traces-config).
 
-This simple example logs trace roots to stdout and is a good way to get started using automatic logging:
+This simple example logs trace roots to `stdout` and is a good way to get started using automatic logging:
 ```yaml
 traces:
   configs:

docs/sources/tempo/configuration/grafana-agent/service-graphs.md

@@ -9,6 +9,8 @@ aliases:
 
 # Enable service graphs
 
+{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+
 A service graph is a visual representation of the interrelationships between various services.
 Service graphs help to understand the structure of a distributed system,
 and the connections and dependencies between its components.
@@ -26,9 +28,13 @@ Service graphs are generated in Grafana Agent and pushed to a Prometheus-compati
 Once generated, they can be represented in Grafana as a graph.
 You need these components to fully use service graphs.
 
-### Enable service graphs in Grafana Agent
+{{< admonition type="note">}}
+Grafana Alloy provides tooling to convert your Agent Static or Flow configuration files into a format that can be used by Alloy.
 
-{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+For more information, refer to [Migrate to Alloy](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/migrate-alloy).
+{{< /admonition>}}
+
+### Enable service graphs in Grafana Agent
 
 To start using service graphs, enable the feature in Grafana Agent configuration.
 

docs/sources/tempo/configuration/grafana-agent/span-metrics.md

@@ -9,6 +9,8 @@ aliases:
 
 # Generate metrics from spans
 
+{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+
 Span metrics allow you to generate metrics from your tracing data automatically.
 Span metrics aggregates request, error and duration (RED) metrics from span data.
 Metrics are exported in Prometheus format.
@@ -26,7 +28,13 @@ The generated metrics show application-level insight into your monitoring,
 as far as tracing gets propagated through your applications.
 
 Span metrics are also used in the service graph view.
-For more information, refer to the [service graph view]({{< relref "../../metrics-generator/service-graph-view" >}}).
+For more information, refer to the [service graph view](https://grafana.com/docs/tempo/<TEMPO_VERSION>/metrics-generator/service-graph-view/).
+
+{{< admonition type="note">}}
+Grafana Alloy provides tooling to convert your Agent Static or Flow configuration files into a format that can be used by Alloy.
+
+For more information, refer to [Migrate to Alloy](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/migrate-alloy).
+{{< /admonition>}}
 
 ## Server-side metrics
 

docs/sources/tempo/configuration/grafana-agent/tail-based-sampling.md

@@ -9,6 +9,8 @@ aliases:
 
 # Tail-based sampling
 
+{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+
 Tempo aims to provide an inexpensive solution that makes 100% sampling possible.
 However, sometimes constraints make a lower sampling percentage necessary or desirable,
 such as runtime or egress traffic related costs.
@@ -57,9 +59,13 @@ If you're using a multi-instance deployment of the agent,
 add load balancing and specify the resolving mechanism to find other Agents in the setup.
 To see all the available configuration options, refer to the [configuration reference](/docs/agent/latest/configuration/traces-config/).
 
-## Example for Grafana Agent Flow
+{{< admonition type="note">}}
+Grafana Alloy provides tooling to convert your Agent Static or Flow configuration files into a format that can be used by Alloy.
 
-{{< docs/shared source="alloy" lookup="agent-deprecation.md" version="next" >}}
+For more information, refer to [Migrate to Alloy](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/migrate-alloy).
+{{< /admonition>}}
+
+### Example for Grafana Agent Flow
 
 [Grafana Agent Flow](/docs/agent/latest/flow/) is a component-based revision of Grafana Agent with a focus on ease-of-use, debuggability, and ability to adapt to the needs of power users.
 Flow configuration files are written in River instead of YAML.

docs/sources/tempo/configuration/grafana-alloy/_index.md

@@ -0,0 +1,141 @@
+---
+title: Grafana Alloy
+description: Configure the Grafana Alloy to work with Tempo
+weight: 550
+aliases:
+- /docs/tempo/grafana-alloy
+---
+
+# Grafana Alloy
+
+Grafana Alloy offers native pipelines for OTel, Prometheus, Pyroscope, Loki, and many other metrics, logs, traces, and profile tools.
+In addition, you can use Alloy pipelines to do other tasks, such as configure alert rules in Loki and Mimir. Alloy is fully compatible with the OTel Collector, Prometheus Agent, and Promtail.
+
+You can use Alloy as an alternative to either of these solutions or combine it into a hybrid system of multiple collectors and agents.
+You can deploy Alloy anywhere within your IT infrastructure and pair it with your Grafana LGTM stack, a telemetry backend from Grafana Cloud, or any other compatible backend from any other vendor.
+Alloy is flexible, and you can easily configure it to fit your needs in on-prem, cloud-only, or a mix of both.
+
+It's commonly used as a tracing pipeline, offloading traces from the
+application and forwarding them to a storage backend.
+
+Grafana Alloy configuration files are written in the [Alloy configuration syntax]([https://grafana.com/docs/agent/latest/flow/concepts/config-language/](https://grafana.com/docs/alloy/latest/concepts/configuration-syntax/)).
+
+For more information, refer to the [Introduction to Grafana Alloy](https://grafana.com/docs/alloy/latest/introduction).
+
+## Architecture
+
+Grafana Alloy can be configured to run a set of tracing pipelines to collect data from your applications and write it to Tempo.
+Pipelines are built using OpenTelemetry, and consist of `receivers`, `processors`, and `exporters`.
+The architecture mirrors that of the OTel Collector's [design](https://github.com/open-telemetry/opentelemetry-collector/blob/846b971758c92b833a9efaf742ec5b3e2fbd0c89/docs/design.md).
+See the [components reference](https://grafana.com/docs/alloy/latest/reference/components/) for all available configuration options.
+
+<p align="center"><img src="https://raw.githubusercontent.com/open-telemetry/opentelemetry-collector/846b971758c92b833a9efaf742ec5b3e2fbd0c89/docs/images/design-pipelines.png" alt="Tracing pipeline architecture"></p>
+
+This lets you configure multiple distinct tracing
+pipelines, each of which collects separate spans and sends them to different
+backends.
+
+### Receiving traces
+<!-- vale Grafana.Parentheses = NO -->
+Grafana Alloy supports multiple ingestion receivers:
+OTLP (OpenTelemetry), Jaeger, Zipkin, OpenCensus, and Kafka.
+<!-- vale Grafana.Parentheses = YES -->
+
+Each tracing pipeline can be configured to receive traces in all these formats.
+Traces that arrive to a pipeline go through the receivers/processors/exporters defined in that pipeline.
+
+### Pipeline processing
+
+Grafana Alloy processes tracing data as it flows through the pipeline to make the distributed tracing system more reliable and leverage the data for other purposes such as trace discovery, tail-based sampling, and generating metrics.
+
+#### Batching
+
+Alloy supports batching of traces.
+Batching helps better compress the data, reduces the number of outgoing connections, and is a recommended best practice.
+To configure it, refer to the `otelcol.processor.batch` block in the [components reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.processor.batch/).
+
+#### Attributes manipulation
+
+Grafana Alloy allows for general manipulation of attributes on spans that pass through it.
+A common use may be to add an environment or cluster variable.
+There are several processors that can manipulate attributes, some examples include: the `otelcol.processor.attributes` block in the [component reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.processor.attributes/) and the `otelcol.processor.transform` block [component reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.processor.transform/)
+
+#### Attaching metadata with Prometheus Service Discovery
+
+Prometheus Service Discovery mechanisms enable you to attach the same metadata to your traces as your metrics.
+For example, for Kubernetes users this means that you can dynamically attach metadata for namespace, Pod, and name of the container sending spans.
+
+
+```alloy
+otelcol.receiver.otlp "default" {
+  http {}
+  grpc {}
+
+  output {
+    traces  = [otelcol.processor.k8sattributes.default.input]
+  }
+}
+
+otelcol.processor.k8sattributes "default" {
+  extract {
+    metadata = [
+      "k8s.namespace.name",
+      "k8s.pod.name",
+      "k8s.container.name"
+    ]
+  }
+
+  output {
+    traces = [otelcol.exporter.otlp.default.input]
+  }
+}
+
+otelcol.exporter.otlp "default" {
+  client {
+    endpoint = env("OTLP_ENDPOINT")
+  }
+}
+```
+
+Refer to the `otelcol.processor.k8sattributes` block in the [components reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.processor.k8sattributes/).
+
+#### Trace discovery through automatic logging
+
+Automatic logging writes well formatted log lines to help with trace discovery.
+
+For a closer look into the feature, visit [Automatic logging](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/automatic-logging/).
+
+#### Tail-based sampling
+
+Alloy implements tail-based sampling for distributed tracing systems and multi-instance Alloy deployments.
+With this feature, you can make sampling decisions based on data from a trace, rather than exclusively with probabilistic methods.
+
+For a detailed description, refer to [Tail-based sampling](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/tail-based-sampling).
+
+#### Generating metrics from spans
+
+Alloy can take advantage of the span data flowing through the pipeline to generate Prometheus metrics.
+
+Refer to [Span metrics](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/span-metrics/) for a more detailed explanation of the feature.
+
+#### Service graph metrics
+
+Service graph metrics represent the relationships between services within a distributed system.
+
+This service graphs processor builds a map of services by analyzing traces, with the objective to find _edges_.
+Edges are spans with a parent-child relationship, that represent a jump, such as a request, between two services.
+The amount of requests and their duration are recorded as metrics, which are used to represent the graph.
+
+To read more about this processor, go to its [section](https://grafana.com/docs/tempo/<TEMPO_VERSION>/configuration/grafana-alloy/service-graphs).
+
+### Exporting spans
+
+Alloy can export traces to multiple different backends for every tracing pipeline.
+Exporting is built using OpenTelemetry Collector's [OTLP exporter](https://github.com/open-telemetry/opentelemetry-collector/blob/846b971758c92b833a9efaf742ec5b3e2fbd0c89/exporter/otlpexporter/README.md).
+Alloy supports exporting tracing in OTLP format.
+
+Aside from endpoint and authentication, the exporter also provides mechanisms for retrying on failure,
+and implements a queue buffering mechanism for transient failures, such as networking issues.
+
+To see all available options,
+refer to the `otelcol.exporter.otlp` block in the [Alloy configuration reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.exporter.otlp/) and the `otelcol.exporter.otlphttp` block in the [Alloy configuration reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.exporter.otlphttp/).

docs/sources/tempo/configuration/grafana-alloy/automatic-logging.md

@@ -0,0 +1,116 @@
+---
+title: 'Automatic logging: Trace discovery through logs'
+description: Automatic logging provides an easy and fast way of getting trace discovery through logs.
+menuTitle: Automatic logging
+weight: 200
+aliases:
+- /docs/tempo/grafana-alloy/automatic-logging
+---
+
+# Automatic logging: Trace discovery through logs
+
+Running instrumented distributed systems is a very powerful way to gain
+understanding over a system, but it brings its own challenges. One of them is
+discovering which traces exist.
+
+Using the span logs connector, you can use Alloy to perform automatic logging.
+
+In the beginning of Tempo, querying for a trace was only possible if you knew
+the ID of the trace you were looking for. One solution was automatic logging.
+Automatic logging provides an easy and fast way of discovering trace IDs
+through log messages.
+Well-formatted log lines are written to a logs exporter
+for each span, root, or process that passes through the tracing
+pipeline. This allows for automatically building a mechanism for trace discovery.
+On top of that, you can also get metrics from traces using a logs source, and
+allow quickly jumping from a log message to the trace view in Grafana.
+
+While this approach is useful, it isn't as powerful as TraceQL. 
+If you are here because you know you want to log the
+trace ID, to enable jumping from logs to traces, then read on.
+
+If you want to query the system directly, read the [TraceQL
+documentation](https://grafana.com/docs/tempo/<TEMPO_VERSION>/traceql).
+
+## Configuration
+
+For high throughput systems, logging for every span may generate too much volume.
+In such cases, logging per root span or process is recommended.
+
+<p align="center"><img src="../tempo-auto-log.svg" alt="Automatic logging overview"></p>
+
+Automatic logging searches for a given set of span or resource attributes in the spans and logs them as key-value pairs.
+This allows searching by those key-value pairs in Loki.
+
+## Before you begin
+
+To configure automatic logging, you need to configure the `otelcol.connector.spanlogs` connector with
+appropriate options.
+
+To see all the available configuration options, refer to the `otelcol.connector.spanlogs` [components reference](https://grafana.com/docs/alloy/latest/reference/components/otelcol.connector.spanlogs/).
+
+This simple example logs trace roots before exporting them to the Grafana OTLP gateway,
+and is a good way to get started using automatic logging:
+
+```alloy
+otelcol.receiver.otlp "default" {
+  grpc {}
+  http {}
+
+  output {
+    traces = [otelcol.connector.spanlogs.default.input]
+  }
+}
+
+otelcol.connector.spanlogs "default" {
+  roots = true
+
+  output {
+    logs = [otelcol.exporter.otlp.default.input]
+  }
+}
+
+otelcol.exporter.otlp "default" {
+  client {
+    endpoint = env("OTLP_ENDPOINT")
+  }
+}
+```
+
+This example logs all trace roots, adding the `http.method` and `http.target` attributes to the log line,
+then pushes logs to a local Loki instance:
+
+```alloy
+otelcol.receiver.otlp "default" {
+  grpc {}
+  http {}
+
+  output {
+    traces = [otelcol.connector.spanlogs.default.input]
+  }
+}
+
+otelcol.connector.spanlogs "default" {
+  roots           = true
+  span_attributes = ["http.method", "http.target"]
+
+  output {
+    logs = [otelcol.exporter.loki.default.input]
+  }
+}
+
+otelcol.exporter.loki "default" {
+  forward_to = [loki.write.local.receiver]
+}
+
+loki.write "local" {
+  endpoint {
+    url = "loki:3100"
+  }
+}
+```
+
+## Examples
+
+<p align="center"><img src="../automatic-logging-example-query.png" alt="Automatic logging overview"></p>
+<p align="center"><img src="../automatic-logging-example-results.png" alt="Automatic logging overview"></p>