Skip to content

Commit cb80420

Browse files
tiffany76chalintheletterf
authored
Add guidance and architecture top-level section (#9531)
Signed-off-by: Tiffany Hrabusa <tiffany.hrabusa@grafana.com> Co-authored-by: Patrice Chalin <chalin@users.noreply.github.com> Co-authored-by: Fabrizio Ferri-Benedetti <algernon@fastmail.com>
1 parent 61e885a commit cb80420

File tree

3 files changed

+68
-0
lines changed

3 files changed

+68
-0
lines changed

content/en/docs/guidance/_index.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Blueprints and reference implementations
3+
description:
4+
Blueprints and sample architectures for best practices when adopting and
5+
implementing OpenTelemetry in common environments
6+
weight: 600
7+
---
8+
9+
Adopting OpenTelemetry at scale is not just a matter of configuring individual
10+
components. It requires coordinated decisions across teams and systems. The
11+
official project documentation explains how specific pieces of OpenTelemetry
12+
work, but many adopters need help connecting those pieces into a cohesive,
13+
production-ready architecture.
14+
15+
This section provides high-level guidance and architectural patterns for
16+
designing and operating OpenTelemetry in real-world environments. It focuses on
17+
the challenges organizations face and maps these challenges to proven approaches
18+
and best practices you can apply in your own environment.
19+
20+
There is no single “correct” way to deploy OpenTelemetry, so this guidance aims
21+
to address all organizational structures, not to force a specific one. With this
22+
flexibility in mind, you can find two types of reference documents in this
23+
section:
24+
25+
- Blueprints are living documents that solve common adoption and implementation
26+
challenges in a given environment. Each blueprint is tightly scoped to address
27+
specific challenges, so you might need to refer to multiple blueprints,
28+
depending on your environment.
29+
- Reference implementations are snapshots in time that show how real-world
30+
organizations use OpenTelemetry to build scalable, resilient pipelines that
31+
send application telemetry to observability backends.
32+
33+
<!-- If your organization has implemented OpenTelemetry and you think others could benefit from your experience, you can propose a new reference implementation by raising an issue in the End User SIG repository. To request a new blueprint for an environment or challenge not already covered, raise an issue using the Blueprints template. TODO: add links to issue template, if possible -->
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Blueprints
3+
description:
4+
Blueprints for best practices when adopting and implementing OpenTelemetry in
5+
common environments
6+
---
7+
8+
Blueprints are living documents that solve common OpenTelemetry adoption and
9+
implementation challenges in a given environment.
10+
11+
Each blueprint is tightly scoped to address specific challenges, so you might
12+
need to refer to multiple blueprints, depending on your environment.
13+
14+
<!-- Add how to propose a new blueprint once the issue template and repo are ready. -->
15+
16+
**Coming soon!**
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: Reference implementations
3+
description:
4+
Examples of how different organizations with different environments have
5+
implemented OpenTelemetry
6+
---
7+
8+
Reference implementations show how real-world organizations use OpenTelemetry to
9+
build scalable, resilient pipelines that send application telemetry to
10+
observability backends. These examples span a range of organizational structures
11+
and technology stacks.
12+
13+
As point-in-time snapshots, reference implementations are not actively
14+
maintained and may not reflect current best practices as the OpenTelemetry
15+
project evolves.
16+
17+
<!-- Add how to propose a new reference implementation once the issue template and repo are ready. -->
18+
19+
**Coming soon!**

0 commit comments

Comments
 (0)