Restructure concept pages for instrumentation (#2763)
Co-authored-by: Patrice Chalin <pchalin@gmail.com>
This commit is contained in:
Severin Neumann
GitHub
parent
ae8cb78ded
commit
249224e8f1
|
|
@ -187,9 +187,8 @@ agent to the host metrics receiver for infrastructure monitoring.
|
|||
|
||||
**A:** It depends on the use cases:
|
||||
|
||||
- [Auto instrumentation](/docs/concepts/instrumenting/#automatic-instrumentation)
|
||||
options are maturing in OTel; for example, the Java JAR agent takes care of
|
||||
instrumenting
|
||||
- [Auto instrumentation](/docs/concepts/instrumentation/automatic/) options are
|
||||
maturing in OTel; for example, the Java JAR agent takes care of instrumenting
|
||||
[most libraries](https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md#libraries--frameworks)
|
||||
that are used by applications. Auto-instrumentation is also available for
|
||||
[Python](/docs/instrumentation/python/automatic/),
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ OpenTelemetry is currently made up of several main components:
|
|||
- [Cross-language specification](/docs/specs/otel/)
|
||||
- [OpenTelemetry Collector](/docs/collector/)
|
||||
- [Per-language SDKs](/docs/instrumentation/)
|
||||
- [Per-language instrumentation libraries](/docs/concepts/instrumenting-library/)
|
||||
- [Per-language automatic instrumentation](/docs/concepts/instrumenting/#automatic-instrumentation)
|
||||
- [Per-language instrumentation libraries](/docs/concepts/instrumentation/libraries/)
|
||||
- [Per-language automatic instrumentation](/docs/concepts/instrumentation/automatic/)
|
||||
- [K8s Operator](/docs/k8s-operator/)
|
||||
|
||||
OpenTelemetry lets you replace the need for vendor-specific SDKs and tools for
|
||||
|
|
@ -56,7 +56,7 @@ preferred backend. These SDKs also let you incorporate instrumentation libraries
|
|||
for common libraries and frameworks that you can use to connect to manual
|
||||
instrumentation in your application.
|
||||
|
||||
For more information, see [Instrumenting](/docs/concepts/instrumenting/).
|
||||
For more information, see [Instrumenting](/docs/concepts/instrumentation/).
|
||||
|
||||
## Instrumentation Libraries
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ It is a long-term goal that popular libraries are authored to be observable out
|
|||
of the box, such that pulling in a separate component is not required.
|
||||
|
||||
For more information, see
|
||||
[Instrumenting Libraries](/docs/concepts/instrumenting-library/).
|
||||
[Instrumenting Libraries](/docs/concepts/instrumentation/libraries/).
|
||||
|
||||
## Automatic Instrumentation
|
||||
|
||||
|
|
@ -80,7 +80,7 @@ OpenTelemetry API and SDK capabilities to your application. Additionally they
|
|||
may add a set of Instrumentation Libraries and exporter dependencies.
|
||||
|
||||
For more information, see
|
||||
[Instrumenting](/docs/concepts/instrumenting/#automatic-instrumentation).
|
||||
[Instrumenting](/docs/concepts/instrumentation/automatic/).
|
||||
|
||||
## K8s operator
|
||||
|
||||
|
|
|
|||
|
|
@ -10,7 +10,7 @@ The OpenTelemetry projects consists of multiple [components](../components) that
|
|||
support multiple [signals](../signals). The reference implementation of
|
||||
OpenTelemetry is available as:
|
||||
|
||||
- [Language-specific instrumentation libraries](../instrumenting)
|
||||
- [Language-specific instrumentation libraries](../instrumentation)
|
||||
- [A Collector binary](../data-collection)
|
||||
|
||||
From any reference implementation a distribution may be created.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,44 @@
|
|||
---
|
||||
title: Instrumentation
|
||||
description: >-
|
||||
How OpenTelemetry facilitates automatic and manual instrumentation of
|
||||
applications.
|
||||
aliases: [/docs/concepts/instrumenting]
|
||||
weight: 15
|
||||
---
|
||||
|
||||
In order to make a system observable, it must be **instrumented**: That is, code
|
||||
from the system's components must emit
|
||||
[traces](/docs/concepts/observability-primer/#distributed-traces),
|
||||
[metrics](/docs/concepts/observability-primer/#reliability--metrics), and
|
||||
[logs](/docs/concepts/observability-primer/#logs).
|
||||
|
||||
Without being required to modify the source code you can collect telemetry from
|
||||
an application using [automatic instrumentation](automatic/). If you previously
|
||||
used an APM agent to extract telemetry from your application, Automatic
|
||||
Instrumentation will give you a similar out of the box experience.
|
||||
|
||||
To facilitate the instrumentation of applications even more, you can
|
||||
[manually instrument](manual/) your applications by coding against the
|
||||
OpenTelemetry APIs.
|
||||
|
||||
For that you don't need to instrument all the dependencies used in your
|
||||
application:
|
||||
|
||||
- some of your libraries will be observable out of the box by calling the
|
||||
OpenTelemetry API themselves directly. Those libraries are sometimes called
|
||||
**natively instrumented**.
|
||||
- for libraries without such an integration the OpenTelemetry projects provide
|
||||
language specific [Instrumentation Libraries][]
|
||||
|
||||
Note, that for most languages it is possible to use both manual and automatic
|
||||
instrumentation at the same time: Automatic Instrumentation will allow you to
|
||||
gain insights into your application quickly and manual instrumentation will
|
||||
enable you to embed granular observability into your code.
|
||||
|
||||
The exact installation mechanism for [manual](manual/) and
|
||||
[automatic](automatic/) instrumentation varies based on the language you’re
|
||||
developing in, but there are some similarities covered in the sections below.
|
||||
|
||||
[instrumentation libraries]:
|
||||
/docs/specs/otel/overview/#instrumentation-libraries
|
||||
|
|
@ -0,0 +1,31 @@
|
|||
---
|
||||
title: Automatic
|
||||
description: >-
|
||||
Learn how Automatic Instrumentation can add observability to your application
|
||||
without the need to touch your code
|
||||
weight: 10
|
||||
---
|
||||
|
||||
If applicable a language specific implementation of OpenTelemetry will provide a
|
||||
way to instrument your application without touching your source code. While the
|
||||
underlying mechanism depends on the language, at a minimum this will add the
|
||||
OpenTelemetry API and SDK capabilities to your application. Additionally they
|
||||
may add a set of Instrumentation Libraries and exporter dependencies.
|
||||
|
||||
Configuration is available via environment variables and possibly language
|
||||
specific means such as system properties in Java. At a minimum, a service name
|
||||
must be configured to identify the service being instrumented. A variety of
|
||||
other configuration options are available and may include:
|
||||
|
||||
- Data source specific configuration
|
||||
- Exporter configuration
|
||||
- Propagator configuration
|
||||
- Resource configuration
|
||||
|
||||
Automatic instrumentation is available for the following languages:
|
||||
|
||||
- [.NET](/docs/instrumentation/net/automatic/)
|
||||
- [Java](/docs/instrumentation/java/automatic/)
|
||||
- [JavaScript](/docs/instrumentation/js/automatic/)
|
||||
- [PHP](/docs/instrumentation/php/automatic/)
|
||||
- [Python](/docs/instrumentation/python/automatic/)
|
||||
|
|
@ -1,6 +1,7 @@
|
|||
---
|
||||
title: Instrumenting libraries
|
||||
title: Libraries
|
||||
description: Learn how to add native instrumentation to your library.
|
||||
aliases: [/docs/concepts/instrumenting-library]
|
||||
weight: 40
|
||||
---
|
||||
|
||||
|
|
@ -172,7 +173,7 @@ out
|
|||
Network calls are usually traced with OpenTelemetry auto-instrumentations
|
||||
through corresponding client implementation.
|
||||
|
||||
|
||||
|
||||
|
||||
If OpenTelemetry does not support tracing your network client, use your best
|
||||
judgement, here are some considerations to help:
|
||||
|
|
@ -1,64 +1,11 @@
|
|||
---
|
||||
title: Instrumenting
|
||||
title: Manual
|
||||
description: >-
|
||||
How OpenTelemetry facilitates automatic and manual instrumentation of
|
||||
applications.
|
||||
weight: 40
|
||||
Learn about the essential steps to manually instrument your application.
|
||||
weight: 20
|
||||
---
|
||||
|
||||
In order to make a system observable, it must be **instrumented**: That is, code
|
||||
from the system's components must emit
|
||||
[traces](/docs/concepts/observability-primer/#distributed-traces),
|
||||
[metrics](/docs/concepts/observability-primer/#reliability--metrics), and
|
||||
[logs](/docs/concepts/observability-primer/#logs).
|
||||
|
||||
Without being required to modify the source code you can collect telemetry from
|
||||
an application using [Automatic Instrumentation][]. If you previously used an
|
||||
APM agent to extract telemetry from your application, Automatic Instrumentation
|
||||
will give you a similar out of the box experience.
|
||||
|
||||
To facilitate the instrumentation of applications even more, you can [manually
|
||||
instrument][] your applications by coding against the OpenTelemetry APIs.
|
||||
|
||||
For that you don't need to instrument all the dependencies used in your
|
||||
application:
|
||||
|
||||
- some of your libraries will be observable out of the box by calling the
|
||||
OpenTelemetry API themselves directly. Those libraries are sometimes called
|
||||
**natively instrumented**.
|
||||
- for libraries without such an integration the OpenTelemetry projects provide
|
||||
language specific [Instrumentation Libraries][]
|
||||
|
||||
Note, that for most languages it is possible to use both manual and automatic
|
||||
instrumentation at the same time: Automatic Instrumentation will allow you to
|
||||
gain insights into your application quickly and manual instrumentation will
|
||||
enable you to embed granular observability into your code.
|
||||
|
||||
The exact installation mechanism for manual and automatic instrumentation varies
|
||||
based on the language you’re developing in, but there are some similarities
|
||||
covered in the sections below.
|
||||
|
||||
## Automatic Instrumentation
|
||||
|
||||
If applicable a language specific implementation of OpenTelemetry will provide a
|
||||
way to instrument your application without touching your source code. While the
|
||||
underlying mechanism depends on the language, at a minimum this will add the
|
||||
OpenTelemetry API and SDK capabilities to your application. Additionally they
|
||||
may add a set of Instrumentation Libraries and exporter dependencies.
|
||||
|
||||
Configuration is available via environment variables and possibly language
|
||||
specific means such as system properties in Java. At a minimum, a service name
|
||||
must be configured to identify the service being instrumented. A variety of
|
||||
other configuration options are available and may include:
|
||||
|
||||
- Data source specific configuration
|
||||
- Exporter configuration
|
||||
- Propagator configuration
|
||||
- Resource configuration
|
||||
|
||||
## Manual Instrumentation
|
||||
|
||||
### Import the OpenTelemetry API and SDK
|
||||
## Import the OpenTelemetry API and SDK
|
||||
|
||||
You'll first need to import OpenTelemetry to your service code. If you're
|
||||
developing a library or some other component that is intended to be consumed by
|
||||
|
|
@ -67,7 +14,7 @@ artifact is a standalone process or service, then you would take a dependency on
|
|||
the API and the SDK. For more information about the OpenTelemetry API and SDK,
|
||||
see the [specification](/docs/specs/otel/).
|
||||
|
||||
### Configure the OpenTelemetry API
|
||||
## Configure the OpenTelemetry API
|
||||
|
||||
In order to create traces or metrics, you'll need to first create a tracer
|
||||
and/or meter provider. In general, we recommend that the SDK should provide a
|
||||
|
|
@ -80,7 +27,7 @@ metric events produced. It is also recommended that you supply a version string
|
|||
(i.e., `semver:1.0.0`) that corresponds to the current version of your library
|
||||
or service.
|
||||
|
||||
### Configure the OpenTelemetry SDK
|
||||
## Configure the OpenTelemetry SDK
|
||||
|
||||
If you're building a service process, you'll also need to configure the SDK with
|
||||
appropriate options for exporting your telemetry data to some analysis backend.
|
||||
|
|
@ -88,7 +35,7 @@ We recommend that this configuration be handled programmatically through a
|
|||
configuration file or some other mechanism. There are also per-language tuning
|
||||
options you may wish to take advantage of.
|
||||
|
||||
### Create Telemetry Data
|
||||
## Create Telemetry Data
|
||||
|
||||
Once you've configured the API and SDK, you'll then be free to create traces and
|
||||
metric events through the tracer and meter objects you obtained from the
|
||||
|
|
@ -96,7 +43,7 @@ provider. Make use of Instrumentation Libraries for your dependencies -- check
|
|||
out the [registry](/ecosystem/registry/) or your language's repository for more
|
||||
information on these.
|
||||
|
||||
### Export Data
|
||||
## Export Data
|
||||
|
||||
Once you've created telemetry data, you'll want to send it somewhere.
|
||||
OpenTelemetry supports two primary methods of exporting data from your process
|
||||
|
|
@ -116,9 +63,3 @@ of analysis tools.
|
|||
In addition to open source tools such as Jaeger or Prometheus, a growing list of
|
||||
companies support ingesting telemetry data from OpenTelemetry. For details, see
|
||||
[Vendors](/ecosystem/vendors/).
|
||||
|
||||
[automatic instrumentation]:
|
||||
/docs/specs/otel/glossary/#automatic-instrumentation
|
||||
[manually instrument]: /docs/specs/otel/glossary/#manual-instrumentation
|
||||
[instrumentation libraries]:
|
||||
/docs/specs/otel/overview/#instrumentation-libraries
|
||||
|
Before Width: | Height: | Size: 48 KiB After Width: | Height: | Size: 48 KiB |
|
|
@ -14,14 +14,14 @@ instrumented automatically and instrumenting your own code with our API
|
|||
manually, we recommend that you learn the following concepts first:
|
||||
|
||||
- [What is OpenTelemetry?](/docs/what-is-opentelemetry/)
|
||||
- [How can I instrument dependencies without touching their code?](/docs/concepts/instrumenting/#automatic-instrumentation)
|
||||
- [How can I instrument my application manually?](/docs/concepts/instrumenting/#manual-instrumentation)
|
||||
- [How can I instrument dependencies without touching their code?](/docs/concepts/instrumentation/automatic/)
|
||||
- [How can I instrument my application manually?](/docs/concepts/instrumentation/manual/)
|
||||
|
||||
If you develop libraries, frameworks or middleware that is used as a dependency
|
||||
within other software, we recommend that you learn how you can provide telemetry
|
||||
natively:
|
||||
|
||||
- [How can I add native instrumentation to my library?](/docs/concepts/instrumenting-library/)
|
||||
- [How can I add native instrumentation to my library?](/docs/concepts/instrumentation/libraries/)
|
||||
|
||||
Next, you can deep dive into the documentations for the
|
||||
[language](/docs/instrumentation/) you are using:
|
||||
|
|
|
|||
|
|
@ -15,7 +15,7 @@ applications without touching their code, we recommend that you learn the
|
|||
following:
|
||||
|
||||
- [What is OpenTelemetry?](/docs/what-is-opentelemetry/)
|
||||
- [How can I instrument applications without touching their code?](/docs/concepts/instrumenting/#automatic-instrumentation)
|
||||
- [How can I instrument applications without touching their code?](/docs/concepts/instrumentation/automatic/)
|
||||
- [How can I set up a collector?](/docs/collector/)
|
||||
- [How can I get automation for Kubernetes with the OpenTelemetry Operator?](/docs/k8s-operator/)
|
||||
|
||||
|
|
|
|||
|
|
@ -27,5 +27,5 @@ follows:
|
|||
|
||||
[auto]:
|
||||
https://github.com/open-telemetry/opentelemetry-operator#opentelemetry-auto-instrumentation-injection
|
||||
[instrumentation]: /docs/concepts/instrumenting/
|
||||
[instrumentation]: /docs/concepts/instrumentation/
|
||||
[otel-op]: https://github.com/open-telemetry/opentelemetry-operator
|
||||
|
|
|
|||
|
|
@ -114,9 +114,9 @@ To do [Tracing](/docs/concepts/signals/traces/) you'll need to acquire a
|
|||
First, a `Tracer` must be acquired, which is responsible for creating spans and
|
||||
interacting with the [Context](../propagation/). A tracer is acquired by using
|
||||
the OpenTelemetry API specifying the name and version of the
|
||||
[library instrumenting](/docs/concepts/instrumenting-library/) the instrumented
|
||||
library or application to be monitored. More information is available in the
|
||||
specification chapter
|
||||
[library instrumenting](/docs/concepts/instrumentation/libraries/) the
|
||||
instrumented library or application to be monitored. More information is
|
||||
available in the specification chapter
|
||||
[Obtaining a Tracer](/docs/specs/otel/trace/api/#tracerprovider).
|
||||
|
||||
```php
|
||||
|
|
|
|||
Loading…
Reference in New Issue