docs: Iterate on the OTel Engine Documentation by blewis12 · Pull Request #5404 · grafana/alloy

blewis12 · 2026-01-30T11:30:50Z

Part of #4722

This addresses a couple points of feedback in the first iteration:

This PR introduces a separate "Introduction" page, which has a high level explanation of the two engines, and outlines the motivation/benefits of the OTel Engine
This main page has a list of components, so far I can't find a way to automate this - but using a dropdown component I feel like the information is more approachable. I've also linked to the OCB manifest just in case folks want to look in more detail
I've included a "Getting Started" page which has concrete examples to get off the ground with the new engine. I've moved the examples away from the CLI docs page to deduplicate

… the CLI docs

github-actions · 2026-01-30T11:32:26Z

💻 Deploy preview deleted (docs: Iterate on the OTel Engine Documentation).

blewis12 · 2026-01-30T11:37:29Z

I can't see the new docs in the preview so i've definitely fudged the setup, would need some guidance there for sure @clayton-cornell

clayton-cornell · 2026-02-02T06:21:34Z

I can't see the new docs in the preview so i've definitely fudged the setup, would need some guidance there for sure

Hmmm... some direct links might help?

There are still a few errors in the markdown draft. Links are broken in at least one place... maybe more.

clayton-cornell

We still need to follow up and check and xref links to make sure they work :-)

docs/sources/reference/cli/otel.md

docs/sources/open-telemetry/_index.md

docs/sources/open-telemetry/get-started.md

docs/sources/reference/cli/otel.md

Copilot

Pull request overview

This PR iterates on the OpenTelemetry (OTel) Engine documentation for Grafana Alloy by improving structure and usability. It introduces a dedicated introduction page explaining the two engines (Default Engine and OTel Engine), adds a getting started guide with concrete examples, and reorganizes component listings using collapsible sections for better readability.

Changes:

Introduces a new "Introduction" page (docs/sources/open-telemetry/_index.md) with high-level explanation of the engines, terminology, and a comprehensive list of included OTel components
Adds a "Getting Started" guide (docs/sources/open-telemetry/get-started.md) with concrete CLI examples for running the OTel Engine with and without the Alloy Engine extension
Creates a new shared experimental stability content file specific to the OTel Engine (docs/sources/shared/stability/experimental_otel.md)
Refactors CLI reference documentation to remove duplicate examples and link to the new getting started guide
Adds parameter definitions for FULL_OTEL_ENGINE, OTEL_ENGINE, and DEFAULT_ENGINE to support consistent terminology

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
docs/sources/shared/stability/experimental_otel.md	New shared content file for OTel Engine experimental feature disclaimer
docs/sources/reference/cli/otel.md	Removed duplicate configuration examples and added link to new getting started guide; improved flag documentation
docs/sources/open-telemetry/get-started.md	New getting started guide with CLI examples for both standalone OTel Engine and with Alloy Engine extension
docs/sources/open-telemetry/_index.md	New introduction page with terminology, component listings in collapsible sections, and overview of the OTel Engine
docs/sources/_index.md.t	Added parameter definitions for engine terminology
docs/sources/_index.md	Added parameter definitions for engine terminology

docs/sources/open-telemetry/get-started.md

docs/sources/opentelemetry/get-started.md

docs/sources/reference/cli/otel.md

docs/sources/shared/stability/experimental_otel.md

docs/sources/reference/cli/otel.md

docs/sources/open-telemetry/_index.md

docs/sources/open-telemetry/get-started.md

docs/sources/reference/cli/otel.md

docs/sources/opentelemetry/_index.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

docs/sources/open-telemetry/_index.md

docs/sources/reference/cli/otel.md

docs/sources/open-telemetry/_index.md

docs/sources/open-telemetry/get-started.md

blewis12 · 2026-02-02T09:20:31Z

docs/sources/opentelemetry/get-started.md

+You can access the {{< param "DEFAULT_ENGINE" >}} UI and metrics on port `12345`.
+
+## Run with {{% param "PRODUCT_NAME" %}} Helm chart
+


@thampiotr a question for you since you're exploring dog fooding. I would like to add a basic helm values snippet here for users, do you happen to have one handy?

Also, I noticed that our most recent helm release 1.5.3 references alloy version 1.12.2 which doesn't yet include the OTel Engine. I assume we'll need to make another release that will reference Alloy 1.13.0 - is this part of the release process already or something we need to do separately?

I don't currently have helm values for it. I may have some later this week. I think it should be quite easy to test it locally with example/kind which can create you local k8s cluster and you can install Alloy using helm chart there.

Yep, updating helm chart should be part of the release. You can override the Alloy image by setting image or something like that in Helm chart's values.yaml.

ah! forgot about the image field..makes sense. I have a basic values file to try out so will give that a whirl

thampiotr

This is looking great, short and easy to understand! Some comments, but nothing dramatic.

docs/sources/open-telemetry/_index.md

docs/sources/open-telemetry/get-started.md

docs/sources/reference/cli/otel.md

docs/sources/shared/stability/experimental_otel.md

docs/sources/opentelemetry/get-started.md

…teration-1

thampiotr

LGTM from my pov

clayton-cornell · 2026-02-05T07:10:09Z

Yup, this iteration added a lot more content and it's looking really good, especially for an Experimental release :-)

blewis12 · 2026-02-06T10:31:24Z

I will merge this as is since the documents are hidden anyway, there's one more comment to address about helm charts which i've left as TODO as I actually suspect we might need to make some changes to the helm chart to get that working. This can be addressed in a follow up

Part of #4722 This addresses a couple points of feedback in the first iteration: * This PR introduces a separate "Introduction" page, which has a high level explanation of the two engines, and outlines the motivation/benefits of the OTel Engine * This main page has a list of components, so far I can't find a way to automate this - but using a dropdown component I feel like the information is more approachable. I've also linked to the OCB manifest just in case folks want to look in more detail * I've included a "Getting Started" page which has concrete examples to get off the ground with the new engine. I've moved the examples away from the CLI docs page to deduplicate --------- Co-authored-by: Clayton Cornell <clayton.cornell@grafana.com> Co-authored-by: Clayton Cornell <131809008+clayton-cornell@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Add a "main" page, with links to a "Getting Started" guide as well as…

ca1f473

… the CLI docs

blewis12 requested a review from clayton-cornell as a code owner January 30, 2026 11:30

blewis12 requested review from jharvey10 and thampiotr January 30, 2026 11:32

blewis12 and others added 2 commits January 30, 2026 12:43

add small note about flags

74c5598

Refactor first draft docs

8eb4796

clayton-cornell reviewed Feb 2, 2026

View reviewed changes

clayton-cornell requested a review from Copilot February 2, 2026 06:26

Copilot started reviewing on behalf of clayton-cornell February 2, 2026 06:26 View session

Copilot AI reviewed Feb 2, 2026

View reviewed changes

Apply suggestions from code review

a82ace5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

clayton-cornell reviewed Feb 2, 2026

View reviewed changes

docs/sources/open-telemetry/_index.md Outdated Show resolved Hide resolved

Update docs/sources/open-telemetry/_index.md

30a2f46

clayton-cornell reviewed Feb 2, 2026

View reviewed changes

docs/sources/reference/cli/otel.md Show resolved Hide resolved

Apply suggestions from code review

df27a23

clayton-cornell reviewed Feb 2, 2026

View reviewed changes

docs/sources/reference/cli/otel.md Outdated Show resolved Hide resolved

docs/sources/open-telemetry/_index.md Outdated Show resolved Hide resolved

docs/sources/open-telemetry/get-started.md Outdated Show resolved Hide resolved

clayton-cornell and others added 2 commits February 1, 2026 23:19

Apply suggestions from code review

eeba4f3

add some more points to the getting started guide

d44bd91

blewis12 commented Feb 2, 2026

View reviewed changes

thampiotr reviewed Feb 2, 2026

View reviewed changes

clayton-cornell added the type/docs Docs Squad label across all Grafana Labs repos label Feb 2, 2026

clayton-cornell and others added 5 commits February 3, 2026 12:21

Rename directory, edit text, include suggestions

80c9efc

link to otlp

4995cbd

remove experimental flag in getting started example for alloy engine

0a23fd3

remove duplicate link to upstream configuration

a3c78bd

Mention plans for FM and link to blog post

1910062

clayton-cornell reviewed Feb 4, 2026

View reviewed changes

docs/sources/opentelemetry/get-started.md Outdated Show resolved Hide resolved

blewis12 added 2 commits February 4, 2026 11:33

remove mention/promise of future fleet management

f1fee0d

Merge branch 'main' into blewis12/improve-otel-engine-documentation-i…

b3b5c08

…teration-1

thampiotr approved these changes Feb 4, 2026

View reviewed changes

clayton-cornell approved these changes Feb 5, 2026

View reviewed changes

modify getting started example to be non GC specific

8a44daa

blewis12 merged commit 13609f0 into main Feb 6, 2026
49 checks passed

blewis12 deleted the blewis12/improve-otel-engine-documentation-iteration-1 branch February 6, 2026 10:31

This was referenced Feb 10, 2026

chore: Cherry Pick OTel Engine New Components and Documentation #5487

Closed

docs: Add helm chart details to OTel Engine docs #5513

Open

		You can access the {{< param "DEFAULT_ENGINE" >}} UI and metrics on port `12345`.

		## Run with {{% param "PRODUCT_NAME" %}} Helm chart

Conversation

blewis12 commented Jan 30, 2026

Uh oh!

github-actions bot commented Jan 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

blewis12 commented Jan 30, 2026

Uh oh!

clayton-cornell commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

clayton-cornell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

blewis12 Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

thampiotr Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

blewis12 Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

thampiotr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

thampiotr left a comment

Choose a reason for hiding this comment

Uh oh!

clayton-cornell commented Feb 5, 2026

Uh oh!

blewis12 commented Feb 6, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Jan 30, 2026 •

edited

Loading

clayton-cornell commented Feb 2, 2026 •

edited

Loading