diff --git a/content/en/blog/2023/end-user-discussions-03.md b/content/en/blog/2023/end-user-discussions-03.md index d267fba78..24714f2c5 100644 --- a/content/en/blog/2023/end-user-discussions-03.md +++ b/content/en/blog/2023/end-user-discussions-03.md @@ -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/), diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index c28d8531e..0dacc503e 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -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 diff --git a/content/en/docs/concepts/distributions.md b/content/en/docs/concepts/distributions.md index 456943c8a..6d2bf53e8 100644 --- a/content/en/docs/concepts/distributions.md +++ b/content/en/docs/concepts/distributions.md @@ -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. diff --git a/content/en/docs/concepts/instrumentation/_index.md b/content/en/docs/concepts/instrumentation/_index.md new file mode 100644 index 000000000..7ce30bb59 --- /dev/null +++ b/content/en/docs/concepts/instrumentation/_index.md @@ -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 diff --git a/content/en/docs/concepts/instrumentation/automatic.md b/content/en/docs/concepts/instrumentation/automatic.md new file mode 100644 index 000000000..cbf460469 --- /dev/null +++ b/content/en/docs/concepts/instrumentation/automatic.md @@ -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/) diff --git a/content/en/docs/concepts/instrumenting-library/index.md b/content/en/docs/concepts/instrumentation/libraries.md similarity index 99% rename from content/en/docs/concepts/instrumenting-library/index.md rename to content/en/docs/concepts/instrumentation/libraries.md index ee0a2cfb1..dbfcca91e 100644 --- a/content/en/docs/concepts/instrumenting-library/index.md +++ b/content/en/docs/concepts/instrumentation/libraries.md @@ -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. -![Nested database and HTTP spans in Jaeger UI](nested-spans.svg) +![Nested database and HTTP spans in Jaeger UI](../nested-spans.svg) If OpenTelemetry does not support tracing your network client, use your best judgement, here are some considerations to help: diff --git a/content/en/docs/concepts/instrumenting.md b/content/en/docs/concepts/instrumentation/manual.md similarity index 50% rename from content/en/docs/concepts/instrumenting.md rename to content/en/docs/concepts/instrumentation/manual.md index 572bb8155..e29e740d4 100644 --- a/content/en/docs/concepts/instrumenting.md +++ b/content/en/docs/concepts/instrumentation/manual.md @@ -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 diff --git a/content/en/docs/concepts/instrumenting-library/nested-spans.svg b/content/en/docs/concepts/instrumentation/nested-spans.svg similarity index 100% rename from content/en/docs/concepts/instrumenting-library/nested-spans.svg rename to content/en/docs/concepts/instrumentation/nested-spans.svg diff --git a/content/en/docs/getting-started/dev.md b/content/en/docs/getting-started/dev.md index babe908d7..2070f795f 100644 --- a/content/en/docs/getting-started/dev.md +++ b/content/en/docs/getting-started/dev.md @@ -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: diff --git a/content/en/docs/getting-started/ops.md b/content/en/docs/getting-started/ops.md index 67d646747..4270b00b5 100644 --- a/content/en/docs/getting-started/ops.md +++ b/content/en/docs/getting-started/ops.md @@ -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/) diff --git a/content/en/docs/instrumentation/_index.md b/content/en/docs/instrumentation/_index.md index 1ed430979..321fd7c1b 100644 --- a/content/en/docs/instrumentation/_index.md +++ b/content/en/docs/instrumentation/_index.md @@ -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 diff --git a/content/en/docs/instrumentation/php/manual.md b/content/en/docs/instrumentation/php/manual.md index cf63fc6c6..e4a7e5e65 100644 --- a/content/en/docs/instrumentation/php/manual.md +++ b/content/en/docs/instrumentation/php/manual.md @@ -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