From 1fe292c4d702a8747c0c18444879abc566bc7d9f Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:19:25 +0200 Subject: [PATCH 01/10] Edits --- content/en/docs/concepts/_index.md | 4 +- content/en/docs/concepts/components.md | 52 +++++------ .../en/docs/concepts/context-propagation.md | 34 ++++---- content/en/docs/concepts/distributions.md | 41 +++++---- content/en/docs/concepts/glossary.md | 71 ++++++++------- .../en/docs/concepts/observability-primer.md | 87 ++++++++++--------- .../en/docs/concepts/semantic-conventions.md | 16 ++-- 7 files changed, 153 insertions(+), 152 deletions(-) diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index 29b6270e3b38..184ef117a9c2 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -6,5 +6,5 @@ aliases: [concepts/overview] weight: 2 --- -In this section you'll learn about the data sources and key components of the -OpenTelemetry project. This will help you understanding how OpenTelemetry works. +In this section you can learn about the data sources and key components of the +OpenTelemetry project. This can help you understand how OpenTelemetry works. diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index bcdaade42ad5..5e99efd9b97b 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -58,69 +58,69 @@ instrumentation in your application. For more information, see [Instrumenting](/docs/concepts/instrumentation/). -### Instrumentation Libraries +### Instrumentation libraries OpenTelemetry supports a broad number of components that generate relevant telemetry data from popular libraries and frameworks for supported languages. -For example, inbound and outbound HTTP requests from an HTTP library will -generate data about those requests. +For example, inbound and outbound HTTP requests from an HTTP library generate +data about those requests. -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. +An aspirational goal of OpenTelemetry is that all popular libraries are built to +be observable by default, so that separate dependencies are not required. For more information, see -[Instrumenting Libraries](/docs/concepts/instrumentation/libraries/). +[Instrumenting libraries](/docs/concepts/instrumentation/libraries/). ### Exporters {{% docs/languages/exporters/intro %}} -### Zero-Code Instrumentation +### Zero-code instrumentation -If applicable a language specific implementation of OpenTelemetry will provide a +If applicable, a language specific implementation of OpenTelemetry provides 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. +underlying mechanism depends on the language, zero-code instrumentation adds the +OpenTelemetry API and SDK capabilities to your application. Additionally, it +might add a set of instrumentation libraries and exporter dependencies. For more information, see -[Zero-Code Instrumentation](/docs/concepts/instrumentation/zero-code/). +[Zero-code instrumentation](/docs/concepts/instrumentation/zero-code/). -### Resource Detectors +### Resource detectors A [resource](/docs/concepts/resources/) represents the entity producing -telemetry as resource attributes. For example, a process producing telemetry +telemetry as resource attributes. For example, a process that produces telemetry that is running in a container on Kubernetes has a Pod name, a namespace, and -possibly a deployment name. All three of these attributes can be included in the +possibly a deployment name. You can include all these attributes in the resource. The language specific implementations of OpenTelemetry provide resource -detection from the environment variable `OTEL_RESOURCE_ATTRIBUTES` and for many -common entities, like process runtime, service, host or operating system. +detection from the `OTEL_RESOURCE_ATTRIBUTES` environment variable and for many +common entities, like process runtime, service, host, or operating system. For more information, see [Resources](/docs/concepts/resources/). -### Cross Service Propagators +### Cross-service propagators Propagation is the mechanism that moves data between services and processes. -Although not limited to tracing, it is what allows traces to build causal +Although not limited to tracing, propagation allows traces to build causal information about a system across services that are arbitrarily distributed across process and network boundaries. -For the vast majority of the use cases, context propagation is done for you -through Instrumentation Libraries. But, if needed you can use `Propagators` +For the vast majority of the use cases, context propagation happens +through instrumentation libraries. If needed, you can use propagators yourself to serialize and deserialize cross-cutting concerns such as the context of a span and [baggage](/docs/concepts/signals/baggage/). -### Sampler +### Samplers Sampling is a process that restricts the amount of traces that are generated by -a system. The language-specific implementations offer several -[head samplers](/docs/concepts/sampling/#head-sampling) +a system. Each language-specific implementation of OpenTelemetry offers several +[head samplers](/docs/concepts/sampling/#head-sampling). For more information, see [Sampling](/docs/concepts/sampling). -## K8s operator +## Kubernetes operator The OpenTelemetry Operator is an implementation of a Kubernetes Operator. The operator manages the OpenTelemetry Collector and auto-instrumentation of the @@ -131,7 +131,7 @@ For more information, see [K8s Operator](/docs/kubernetes/operator/). ## Function as a Service assets OpenTelemetry supports various methods of monitoring Function-as-a-Service -provided by different cloud vendors The OpenTelemetry community currently +provided by different cloud vendors. The OpenTelemetry community currently provides pre-built Lambda layers able to auto-instrument your application as well as a the option of standalone Collector Lambda layer that can be used when instrumenting applications manually or automatically. diff --git a/content/en/docs/concepts/context-propagation.md b/content/en/docs/concepts/context-propagation.md index d6e38872acfa..bdc6ff3e6b59 100644 --- a/content/en/docs/concepts/context-propagation.md +++ b/content/en/docs/concepts/context-propagation.md @@ -4,35 +4,37 @@ weight: 10 description: Learn about the concept that enables Distributed Tracing. --- -With Context Propagation, [Signals](/docs/concepts/signals) can be correlated +With context propagation, [Signals](/docs/concepts/signals) can be correlated with each other, regardless of where they are generated. Although not limited to -tracing, it is what allows [traces](/docs/concepts/signals/traces) to build -causal information about a system across services that are arbitrarily +tracing, context propagation allows [traces](/docs/concepts/signals/traces) to +build causal information about a system across services that are arbitrarily distributed across process and network boundaries. -We define Context Propagation by two sub-concepts: Context and Propagation. +To understand context propagation, you need to understand two separate concepts: +context and propagation. ## Context -A **Context** is an object that contains the information for the sending and -receiving service (or -[execution unit](/docs/specs/otel/glossary/#execution-unit)) to correlate one +Context is an object that contains the information for the sending and +receiving service, or +[execution unit](/docs/specs/otel/glossary/#execution-unit), to correlate one signal with another. -For example, if Service A calls Service B, then a span from Service A whose ID +For example, if service A calls service B, then a span from service A whose ID is in context will be used as the parent span for the next span created in -Service B. The trace ID that is in context will be used for the next span -created in Service B as well, which signifies that the span is part of the same -trace as the span from Service A. +service B. The trace ID that is in context will be used for the next span +created in service B as well, which means that the span is part of the same +trace as the span from service A. ## Propagation -**Propagation** is the mechanism that moves context between services and +Propagation is the mechanism that moves context between services and processes. It serializes or deserializes the context object and provides the -relevant information to be propagated from one service to another. Propagation -is usually handled by instrumentation libraries and is transparent to the user, -but in the event that you need to manually propagate context, you can use -Propagation APIs. +relevant information to be propagated from one service to another. + +Propagation is usually handled by instrumentation libraries and is transparent +to the user. In the event that you need to manually propagate context, you can +use Propagation APIs. OpenTelemetry maintains several official propagators. The default propagator is using the headers specified by the diff --git a/content/en/docs/concepts/distributions.md b/content/en/docs/concepts/distributions.md index 42b5d3fd8be6..aa515dea1ebe 100644 --- a/content/en/docs/concepts/distributions.md +++ b/content/en/docs/concepts/distributions.md @@ -13,14 +13,15 @@ OpenTelemetry is available as: - [Language-specific instrumentation libraries](../instrumentation) - A [Collector binary](/docs/concepts/components/#collector) -From any reference implementation a distribution may be created. +Any reference implementation can be customized as a distribution. ## What is a distribution? -A distribution, not to be confused with a fork, is customized version of an -OpenTelemetry component. A distribution is a wrapper around an upstream -OpenTelemetry repository with some customizations. Customizations in a -distribution may include: +A distribution is a customized version of an OpenTelemetry component. A +distribution is a wrapper around an upstream OpenTelemetry repository with +some customizations. Distributions are not to be confused with forks. + +Customizations in a distribution may include: - Scripts to ease use or customize use for a specific backend or vendor - Changes to default settings required for a backend, vendor, or end-user @@ -29,27 +30,25 @@ distribution may include: - Additional capabilities beyond what OpenTelemetry provides - Less capabilities from what OpenTelemetry provides -Distributions would broadly fall into the following categories: +Distributions broadly fall into the following categories: - **"Pure":** These distributions provide the same functionality as upstream and - are 100% compatible. Customizations would typically be to ease of use or + are 100% compatible. Customizations typically enhance the ease of use or packaging. These customizations may be backend, vendor, or end-user specific. -- **"Plus":** These distributions provide the same functionality as upstream - plus more. Customizations beyond those found in pure distributions would be - the inclusion of additional components. Examples of this would include - instrumentation libraries or vendor exporters not upstreamed to the - OpenTelemetry project. -- **"Minus":** These distributions provide a reduced set of functionality from - upstream. Examples of this would include the removal of instrumentation - libraries or receivers/processors/exporters/extensions found in the +- **"Plus":** These distributions provide added functionalities on top of + upstream through additional components. Examples include instrumentation + libraries or vendor exporters not upstreamed to the OpenTelemetry project. +- **"Minus":** These distributions provide a subset of functionality from + upstream. Examples of this include the removal of instrumentation + libraries or receivers, processors, exporters, or extensions found in the OpenTelemetry Collector project. These distributions may be provided to increase supportability and security considerations. -## Who would create a distribution? +## Who can create a distribution? -Anyone could create a distribution. Today, several +Anyone can create a distribution. Today, several [vendors](/ecosystem/vendors/) offer [distributions](/ecosystem/distributions/). -In addition, end-users can consider creating a distribution if they wish to use +In addition, end-users can consider creating a distribution if they want to use components in the [Registry](/ecosystem/registry/) that are not upstreamed to the OpenTelemetry project. @@ -63,7 +62,7 @@ implementations: - Can your scripts for "ease of use" be generalized? - Can your changes to default settings be the better option for everyone? - Are your additional packaging options really specific? -- Might your test, performance & security coverage work with the reference +- Might your test, performance and security coverage work with the reference implementation as well? - Have you checked with the community if your additional capabilities could be part of the standard? @@ -79,14 +78,14 @@ If you are building your own distribution, the [OpenTelemetry Collector Builder](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder) might be a good starting point. -### Language Specific Instrumentation libraries +### Language specific instrumentation libraries There are language specific extensibility mechanisms to customize the instrumentation libraries: - [Java agent](/docs/zero-code/java/agent/extensions) -## What you should know about distributions +## Follow the guidelines When using OpenTelemetry project collateral such as logo and name for your distribution, make sure that you are in line with the [OpenTelemetry Marketing diff --git a/content/en/docs/concepts/glossary.md b/content/en/docs/concepts/glossary.md index 751e3d163f9d..4e146984d26f 100644 --- a/content/en/docs/concepts/glossary.md +++ b/content/en/docs/concepts/glossary.md @@ -6,11 +6,11 @@ description: >- weight: 200 --- -The OpenTelemetry project uses terminology you may or may not be familiar with. -In addition, the project may define the terminology in a different way than +The OpenTelemetry project uses terminology you might not be familiar with. +In addition, the project defines the terminology in a different way than others. This page captures terminology used in the project and what it means. -## Generic Terminology +## Generic terminology ### **Aggregation** @@ -22,7 +22,7 @@ during program execution. Used by the [`Metric`](#metric) ### **API** Application Programming Interface. In the OpenTelemetry project, used to define -how telemetry data is generated per [`Data Source`](#data-source). +how telemetry data is generated per [`Data source`](#data-source). ### **Application** @@ -31,16 +31,16 @@ One or more [`Services`](#service) designed for end users or other applications. ### **APM** Application Performance Monitoring is about monitoring software applications, -their performance (speed, reliability, availability, etc.) to detect issues, -alerting and tooling for finding the root cause. +their performance (speed, reliability, availability, and so on) to detect +issues, alerting and tooling for finding the root cause. ### **Attribute** -OpenTelemetry's word for [`Metadata`](#metadata). Adds key-value information to +OpenTelemetry term for [`Metadata`](#metadata). Adds key-value information to the entity producing telemetry. Used across [`Signals`](#signal) and [`Resources`](#resource). See [attribute spec][attribute]. -### **Automatic Instrumentation** +### **Automatic instrumentation** Refers to telemetry collection methods that do not require the end-user to modify application's source code. Methods vary by programming language, and @@ -51,11 +51,11 @@ examples include bytecode injection or monkey patching. A mechanism for propagating [`Metadata`](#metadata) to help establish a causal relationship between events and services. See [baggage spec][baggage]. -### **Client Library** +### **Client library** -See [`Instrumented Library`](#instrumented-library). +See [`Instrumented library`](#instrumented-library). -### **Client-side App** +### **Client-side app** A component of an [`Application`](#application) that is not running inside a private infrastructure and is typically used directly by end-users. Examples of @@ -76,9 +76,9 @@ Several [`Instrumentation Libraries`](#instrumentation-library) and the dedicated contrib repository for non-core capabilities including vendor `Exporters`. -### **Context Propagation** +### **Context propagation** -Allows all [`Data Sources`](#data-source) to share an underlying context +Allows all [`Data sources`](#data-source) to share an underlying context mechanism for storing state and accessing data across the lifespan of a [`Transaction`](#transaction). See [context propagation spec][context propagation]. @@ -87,7 +87,7 @@ spec][context propagation]. [Directed Acyclic Graph][dag]. -### **Data Source** +### **Data source** See [`Signal`](#signal) @@ -95,14 +95,14 @@ See [`Signal`](#signal) A term used specifically by [`Metrics`](#metric). See [`Attribute`](#attribute). -### **Distributed Tracing** +### **Distributed tracing** Tracks the progression of a single [`Request`](#request), called a [`Trace`](#trace), as it is handled by [`Services`](#service) that make up an -[`Application`](#application). A [`Distributed Trace`](#distributed-tracing) +[`Application`](#application). A [`Distributed trace`](#distributed-tracing) transverses process, network and security boundaries. -More on Distributed Tracing [here][distributed tracing]. +See [Distributed tracing][distributed tracing]. ### **Distribution** @@ -112,7 +112,7 @@ some customizations. See [more][distribution]. ### **Event** Something that happened where representation depends on the -[`Data Source`](#data-source). For example, [`Spans`](#span). +[`Data source`](#data-source). For example, [`Spans`](#span). ### **Exporter** @@ -136,20 +136,20 @@ A high-performance, open source universal [`RPC`](#rpc) framework. More on gRPC Short for [Hypertext Transfer Protocol][http]. -### **Instrumented Library** +### **Instrumented library** Denotes the [`Library`](#library) for which the telemetry signals ([`Traces`](#trace), [`Metrics`](#metric), [`Logs`](#log)) are gathered. See [more][spec-instrumented-lib]. -### **Instrumentation Library** +### **Instrumentation library** Denotes the [`Library`](#library) that provides the instrumentation for a given -[`Instrumented Library`](#instrumented-library). -[`Instrumented Library`](#instrumented-library) and -[`Instrumentation Library`](#instrumentation-library) may be the same +[`Instrumented library`](#instrumented-library). +[`Instrumented library`](#instrumented-library) and +[`Instrumentation library`](#instrumentation-library) can be the same [`Library`](#library) if it has built-in OpenTelemetry instrumentation. See -[more][spec-instrumentation-lib]. +[the lib specification][spec-instrumentation-lib]. ### **JSON** @@ -169,17 +169,16 @@ A language-specific collection of behavior invoked by an interface. ### **Log** -Sometimes used to refer to a collection of [`Log Records`](#log-record). May be +Sometimes used to refer to a collection of [`Log records`](#log-record). Can be ambiguous since people also sometimes use [`Log`](#log) to refer to a single -[`Log Record`](#log-record), thus this term should be used carefully and in the -context where ambiguity is possible additional qualifiers should be used (e.g. -`Log Record`). See [more][log]. +[`Log record`](#log-record). Where ambiguity is possible, use additional +qualifiers, for example, `Log record`. See [more][log] -### **Log Record** +### **Log record** -A recording of an [`Event`](#event). Typically the record includes a timestamp +A recording of an [`Event`](#event). Typically. the record includes a timestamp indicating when the [`Event`](#event) happened as well as other data that -describes what happened, where it happened, etc. See [more][log record]. +describes what happened, where it happened, and so on. See [more][log record]. ### **Metadata** @@ -251,7 +250,7 @@ See [`Distributed Tracing`](#distributed-tracing). Captures information about the entity producing telemetry as [`Attributes`](#attribute). For example, a process producing telemetry that is running in a container on Kubernetes has a process name, a pod name, a -namespace, and possibly a deployment name. All four of these attributes can be +namespace, and possibly a deployment name. All these attributes can be included in the `Resource`. ### **REST** @@ -272,7 +271,7 @@ A mechanism to control the amount of data exported. Most commonly used with the Short for Software Development Kit. Refers to a telemetry SDK that denotes a [`Library`](#library) that implement the OpenTelemetry [`API`](#api). -### **Semantic Conventions** +### **Semantic conventions** Defines standard names and values of [`Metadata`](#metadata) in order to provide vendor-agnostic telemetry data. @@ -281,7 +280,7 @@ vendor-agnostic telemetry data. A component of an [`Application`](#application). Multiple instances of a [`Service`](#service) are typically deployed for high availability and -scalability. A [`Service`](#service) may be deployed in multiple locations. +scalability. A [`Service`](#service) can be deployed in multiple locations. ### **Signal** @@ -292,7 +291,7 @@ Signals [here][signals]. Represents a single operation within a [`Trace`](#trace). See [more][span]. -### **Span Link** +### **Span link** A span link is a link between causally-related spans. For details see [Links between spans](/docs/specs/otel/overview#links-between-spans) and @@ -315,7 +314,7 @@ See [`Metadata`](#metadata). ### **Trace** A [`DAG`](#dag) of [`Spans`](#span), where the edges between [`Spans`](#span) -are defined as parent/child relationship. See [more][trace]. +are defined as parent-child relationship. See [more][trace]. ### **Tracer** diff --git a/content/en/docs/concepts/observability-primer.md b/content/en/docs/concepts/observability-primer.md index 61a5b4d9497d..9a9d5833b3cf 100644 --- a/content/en/docs/concepts/observability-primer.md +++ b/content/en/docs/concepts/observability-primer.md @@ -7,12 +7,12 @@ cSpell:ignore: webshop ## What is Observability? -Observability lets us understand a system from the outside, by letting us ask +Observability lets you understand a system from the outside by letting you ask questions about that system without knowing its inner workings. Furthermore, it -allows us to easily troubleshoot and handle novel problems (i.e. "unknown -unknowns”), and helps us answer the question, "Why is this happening?" +allows you to easily troubleshoot and handle novel problems, that is, "unknown +unknowns”. It also helps you answer the question "Why is this happening?" -In order to be able to ask those questions of a system, the application must be +To ask those questions about your system, your application must be properly instrumented. That is, the application code must emit [signals](/docs/concepts/signals/) such as [traces](/docs/concepts/signals/traces/), @@ -22,45 +22,51 @@ when developers don't need to add more instrumentation to troubleshoot an issue, because they have all of the information they need. [OpenTelemetry](/docs/what-is-opentelemetry/) is the mechanism by which -application code is instrumented, to help make a system observable. +application code is instrumented to help make a system observable. -## Reliability & Metrics +## Reliability and metrics -**Telemetry** refers to data emitted from a system, about its behavior. The data +**Telemetry** refers to data emitted from a system and its behavior. The data can come in the form of [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), and [logs](/docs/concepts/signals/logs/). **Reliability** answers the question: "Is the service doing what users expect it to be doing?” A system could be up 100% of the time, but if, when a user clicks -"Add to Cart” to add a black pair of shoes to their shopping cart, and instead, -the system doesn't always add black shoes, then the system would be said to be -**un**reliable. +"Add to Cart” to add a black pair of shoes to their shopping cart, the system +doesn't always add black shoes, then the system could be **un**reliable. **Metrics** are aggregations over a period of time of numeric data about your infrastructure or application. Examples include: system error rate, CPU -utilization, request rate for a given service. For more on metrics and how they -pertain to OpenTelemetry, see [Metrics](/docs/concepts/signals/metrics/). +utilization, and request rate for a given service. For more on metrics and how +they relate to OpenTelemetry, see [Metrics](/docs/concepts/signals/metrics/). **SLI**, or Service Level Indicator, represents a measurement of a service's behavior. A good SLI measures your service from the perspective of your users. An example SLI can be the speed at which a web page loads. -**SLO**, or Service Level Objective, is the means by which reliability is -communicated to an organization/other teams. This is accomplished by attaching -one or more SLIs to business value. +**SLO**, or Service Level Objective, represents the means by which reliability +is communicated to an organization/other teams. This is accomplished by +attaching one or more SLIs to business value. -## Understanding Distributed Tracing +## Understanding distributed tracing -To understand Distributed Tracing, let's start with some basics. +Distributed tracing lets you observe requests as they propagate through complex, +distributed systems. Distributed tracing improves the visibility of your +application or system's health and lets you debug behavior that is difficult to +reproduce locally. It is essential for distributed systems, which commonly +have nondeterministic problems or are too complicated to reproduce locally. + +To understand distributed tracing, you need to understand the role of each of +its components: logs, spans, and traces. ### Logs A **log** is a timestamped message emitted by services or other components. -Unlike [traces](#distributed-traces), however, they are not necessarily -associated with any particular user request or transaction. They are found -almost everywhere in software, and have been heavily relied on in the past by -both developers and operators alike to help them understand system behavior. +Unlike [traces](#distributed-traces), they aren't necessarily associated with +any particular user request or transaction. You can find logs almost everywhere +in software. Logs have been heavily relied on in the past by both developers and +operators to help them understand system behavior. Sample log: @@ -68,20 +74,20 @@ Sample log: I, [2021-02-23T13:26:23.505892 #22473] INFO -- : [6459ffe1-ea53-4044-aaa3-bf902868f730] Started GET "/" for ::1 at 2021-02-23 13:26:23 -0800 ``` -Unfortunately, logs aren't extremely useful for tracking code execution, as they -typically lack contextual information, such as where they were called from. +Logs aren't enough for tracking code execution, as they usually lack contextual +information, such as where they were called from. They become far more useful when they are included as part of a [span](#spans), or when they are correlated with a trace and a span. -For more on logs and how they pertain to OTel, see +For more on logs and how they pertain to OpenTelemetry, see [Logs](/docs/concepts/signals/logs/). ### Spans -A **span** represents a unit of work or operation. It tracks specific operations -that a request makes, painting a picture of what happened during the time in -which that operation was executed. +A **span** represents a unit of work or operation. Spans track specific +operations that a request makes, painting a picture of what happened during the +time in which that operation was executed. A span contains name, time-related data, [structured log messages](/docs/concepts/signals/traces/#span-events), and @@ -90,6 +96,8 @@ to provide information about the operation it tracks. #### Span attributes +Span attributes are metadata attached to a span. + The following table contains examples of span attributes: | Key | Value | @@ -107,34 +115,27 @@ The following table contains examples of span attributes: | `client.socket.address` | `"192.0.2.5"` (the client goes through a proxy) | | `user_agent.original` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | -For more on spans and how they pertain to OpenTelemetry, see +For more on spans and how they relate to OpenTelemetry, see [Spans](/docs/concepts/signals/traces/#spans). -### Distributed Traces +### Distributed traces A **distributed trace**, more commonly known as a **trace**, records the paths taken by requests (made by an application or end-user) as they propagate through multi-service architectures, like microservice and serverless applications. -Without tracing, it is challenging to pinpoint the cause of performance problems -in a distributed system. - -It improves the visibility of our application or system's health and lets us -debug behavior that is difficult to reproduce locally. Tracing is essential for -distributed systems, which commonly have nondeterministic problems or are too -complicated to reproduce locally. - -Tracing makes debugging and understanding distributed systems less daunting by -breaking down what happens within a request as it flows through a distributed -system. - A trace is made of one or more spans. The first span represents the root span. Each root span represents a request from start to finish. The spans underneath the parent provide a more in-depth context of what occurs during a request (or what steps make up a request). -Many Observability backends visualize traces as waterfall diagrams that may look -something like this: +Without tracing, finding the root cause of performance problems in a distributed +system can be challenging. Tracing makes debugging and understanding distributed +systems less daunting by breaking down what happens within a request as it flows +through a distributed system. + +Many Observability backends visualize traces as waterfall diagrams that look +like this: ![Sample Trace](/img/waterfall-trace.svg 'Trace waterfall diagram') diff --git a/content/en/docs/concepts/semantic-conventions.md b/content/en/docs/concepts/semantic-conventions.md index 3a24bea93708..b21517fbced4 100644 --- a/content/en/docs/concepts/semantic-conventions.md +++ b/content/en/docs/concepts/semantic-conventions.md @@ -4,15 +4,15 @@ description: Common names for different kinds of operations and data. weight: 30 --- -OpenTelemetry defines [Semantic Conventions](/docs/specs/semconv/) (sometimes -called Semantic Attributes) that specify common names for different kinds of -operations and data. The benefit of using Semantic Conventions is in following a +OpenTelemetry defines [Semantic Conventions](/docs/specs/semconv/), sometimes +called Semantic attributes, that specify common names for different kinds of +operations and data. The benefit of using Semantic conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. -Semantic Conventions are available for traces, metrics, logs, and resources: +Semantic conventions are available for traces, metrics, logs, and resources: -- [Trace Semantic Conventions](/docs/specs/semconv/general/trace/) -- [Metric Semantic Conventions](/docs/specs/semconv/general/metrics/) -- [Log Semantic Conventions](/docs/specs/semconv/general/logs/) -- [Resource Semantic Conventions](/docs/specs/semconv/resource/) +- [Trace semantic conventions](/docs/specs/semconv/general/trace/) +- [Metric semantic conventions](/docs/specs/semconv/general/metrics/) +- [Log semantic conventions](/docs/specs/semconv/general/logs/) +- [Resource semantic conventions](/docs/specs/semconv/resource/) From 6898a393137826392dcbc9fd997d6e66fa0a4a71 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:21:09 +0200 Subject: [PATCH 02/10] Fix format --- content/en/docs/concepts/components.md | 8 +++---- .../en/docs/concepts/context-propagation.md | 13 +++++------ content/en/docs/concepts/distributions.md | 22 +++++++++---------- content/en/docs/concepts/glossary.md | 14 ++++++------ .../en/docs/concepts/observability-primer.md | 8 +++---- 5 files changed, 32 insertions(+), 33 deletions(-) diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index 5e99efd9b97b..1871b451dd09 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -107,10 +107,10 @@ Although not limited to tracing, propagation allows traces to build causal information about a system across services that are arbitrarily distributed across process and network boundaries. -For the vast majority of the use cases, context propagation happens -through instrumentation libraries. If needed, you can use propagators -yourself to serialize and deserialize cross-cutting concerns such as the context -of a span and [baggage](/docs/concepts/signals/baggage/). +For the vast majority of the use cases, context propagation happens through +instrumentation libraries. If needed, you can use propagators yourself to +serialize and deserialize cross-cutting concerns such as the context of a span +and [baggage](/docs/concepts/signals/baggage/). ### Samplers diff --git a/content/en/docs/concepts/context-propagation.md b/content/en/docs/concepts/context-propagation.md index bdc6ff3e6b59..2bc5ba429620 100644 --- a/content/en/docs/concepts/context-propagation.md +++ b/content/en/docs/concepts/context-propagation.md @@ -15,10 +15,9 @@ context and propagation. ## Context -Context is an object that contains the information for the sending and -receiving service, or -[execution unit](/docs/specs/otel/glossary/#execution-unit), to correlate one -signal with another. +Context is an object that contains the information for the sending and receiving +service, or [execution unit](/docs/specs/otel/glossary/#execution-unit), to +correlate one signal with another. For example, if service A calls service B, then a span from service A whose ID is in context will be used as the parent span for the next span created in @@ -28,9 +27,9 @@ trace as the span from service A. ## Propagation -Propagation is the mechanism that moves context between services and -processes. It serializes or deserializes the context object and provides the -relevant information to be propagated from one service to another. +Propagation is the mechanism that moves context between services and processes. +It serializes or deserializes the context object and provides the relevant +information to be propagated from one service to another. Propagation is usually handled by instrumentation libraries and is transparent to the user. In the event that you need to manually propagate context, you can diff --git a/content/en/docs/concepts/distributions.md b/content/en/docs/concepts/distributions.md index aa515dea1ebe..d2ee15145e90 100644 --- a/content/en/docs/concepts/distributions.md +++ b/content/en/docs/concepts/distributions.md @@ -18,8 +18,8 @@ Any reference implementation can be customized as a distribution. ## What is a distribution? A distribution is a customized version of an OpenTelemetry component. A -distribution is a wrapper around an upstream OpenTelemetry repository with -some customizations. Distributions are not to be confused with forks. +distribution is a wrapper around an upstream OpenTelemetry repository with some +customizations. Distributions are not to be confused with forks. Customizations in a distribution may include: @@ -39,18 +39,18 @@ Distributions broadly fall into the following categories: upstream through additional components. Examples include instrumentation libraries or vendor exporters not upstreamed to the OpenTelemetry project. - **"Minus":** These distributions provide a subset of functionality from - upstream. Examples of this include the removal of instrumentation - libraries or receivers, processors, exporters, or extensions found in the - OpenTelemetry Collector project. These distributions may be provided to - increase supportability and security considerations. + upstream. Examples of this include the removal of instrumentation libraries or + receivers, processors, exporters, or extensions found in the OpenTelemetry + Collector project. These distributions may be provided to increase + supportability and security considerations. ## Who can create a distribution? -Anyone can create a distribution. Today, several -[vendors](/ecosystem/vendors/) offer [distributions](/ecosystem/distributions/). -In addition, end-users can consider creating a distribution if they want to use -components in the [Registry](/ecosystem/registry/) that are not upstreamed to -the OpenTelemetry project. +Anyone can create a distribution. Today, several [vendors](/ecosystem/vendors/) +offer [distributions](/ecosystem/distributions/). In addition, end-users can +consider creating a distribution if they want to use components in the +[Registry](/ecosystem/registry/) that are not upstreamed to the OpenTelemetry +project. ## Contribution or distribution? diff --git a/content/en/docs/concepts/glossary.md b/content/en/docs/concepts/glossary.md index 4e146984d26f..7ddedec757c1 100644 --- a/content/en/docs/concepts/glossary.md +++ b/content/en/docs/concepts/glossary.md @@ -6,9 +6,9 @@ description: >- weight: 200 --- -The OpenTelemetry project uses terminology you might not be familiar with. -In addition, the project defines the terminology in a different way than -others. This page captures terminology used in the project and what it means. +The OpenTelemetry project uses terminology you might not be familiar with. In +addition, the project defines the terminology in a different way than others. +This page captures terminology used in the project and what it means. ## Generic terminology @@ -148,8 +148,8 @@ Denotes the [`Library`](#library) that provides the instrumentation for a given [`Instrumented library`](#instrumented-library). [`Instrumented library`](#instrumented-library) and [`Instrumentation library`](#instrumentation-library) can be the same -[`Library`](#library) if it has built-in OpenTelemetry instrumentation. See -[the lib specification][spec-instrumentation-lib]. +[`Library`](#library) if it has built-in OpenTelemetry instrumentation. See [the +lib specification][spec-instrumentation-lib]. ### **JSON** @@ -250,8 +250,8 @@ See [`Distributed Tracing`](#distributed-tracing). Captures information about the entity producing telemetry as [`Attributes`](#attribute). For example, a process producing telemetry that is running in a container on Kubernetes has a process name, a pod name, a -namespace, and possibly a deployment name. All these attributes can be -included in the `Resource`. +namespace, and possibly a deployment name. All these attributes can be included +in the `Resource`. ### **REST** diff --git a/content/en/docs/concepts/observability-primer.md b/content/en/docs/concepts/observability-primer.md index 9a9d5833b3cf..e50db9dbbf35 100644 --- a/content/en/docs/concepts/observability-primer.md +++ b/content/en/docs/concepts/observability-primer.md @@ -12,8 +12,8 @@ questions about that system without knowing its inner workings. Furthermore, it allows you to easily troubleshoot and handle novel problems, that is, "unknown unknowns”. It also helps you answer the question "Why is this happening?" -To ask those questions about your system, your application must be -properly instrumented. That is, the application code must emit +To ask those questions about your system, your application must be properly +instrumented. That is, the application code must emit [signals](/docs/concepts/signals/) such as [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), and @@ -54,8 +54,8 @@ attaching one or more SLIs to business value. Distributed tracing lets you observe requests as they propagate through complex, distributed systems. Distributed tracing improves the visibility of your application or system's health and lets you debug behavior that is difficult to -reproduce locally. It is essential for distributed systems, which commonly -have nondeterministic problems or are too complicated to reproduce locally. +reproduce locally. It is essential for distributed systems, which commonly have +nondeterministic problems or are too complicated to reproduce locally. To understand distributed tracing, you need to understand the role of each of its components: logs, spans, and traces. From 6ba8a340a9b0a2cf1935cc227bbe211cbc9cdabe Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:22:55 +0200 Subject: [PATCH 03/10] Links --- content/en/docs/concepts/components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index 1871b451dd09..d9bd600f133e 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -15,8 +15,8 @@ OpenTelemetry is currently made up of several main components: - [Zero-Code Instrumentation](#zero-code-instrumentation) - [Resource Detectors](#resource-detectors) - [Cross Service Propagators](#cross-service-propagators) - - [Sampler](#sampler) -- [K8s operator](#k8s-operator) + - [Sampler](#samplers) +- [K8s operator](#kubernetes-operator) - [Function as a Service assets](#function-as-a-service-assets) OpenTelemetry lets you replace the need for vendor-specific SDKs and tools for From 9c98d53ee6595a8b87959cfb27c5ce5a2c0db5cd Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:24:03 +0200 Subject: [PATCH 04/10] Title capitalization --- content/en/docs/concepts/context-propagation.md | 2 +- content/en/docs/concepts/observability-primer.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/context-propagation.md b/content/en/docs/concepts/context-propagation.md index 2bc5ba429620..31537ffddc70 100644 --- a/content/en/docs/concepts/context-propagation.md +++ b/content/en/docs/concepts/context-propagation.md @@ -1,5 +1,5 @@ --- -title: Context Propagation +title: Context propagation weight: 10 description: Learn about the concept that enables Distributed Tracing. --- diff --git a/content/en/docs/concepts/observability-primer.md b/content/en/docs/concepts/observability-primer.md index e50db9dbbf35..f22da8122eac 100644 --- a/content/en/docs/concepts/observability-primer.md +++ b/content/en/docs/concepts/observability-primer.md @@ -1,5 +1,5 @@ --- -title: Observability Primer +title: Observability primer description: Core observability concepts. weight: 9 cSpell:ignore: webshop From 56c788c17ba2a619af302115aba1e5d274b113bf Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:30:07 +0200 Subject: [PATCH 05/10] Definitions --- .../concepts/instrumentation-scope/index.md | 39 +++++++++---------- content/en/docs/concepts/signals/baggage.md | 2 +- content/en/docs/concepts/signals/logs.md | 1 + content/en/docs/concepts/signals/metrics.md | 2 +- content/en/docs/concepts/signals/traces.md | 2 +- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/content/en/docs/concepts/instrumentation-scope/index.md b/content/en/docs/concepts/instrumentation-scope/index.md index 1f1cd390ca67..7d6e676d7528 100644 --- a/content/en/docs/concepts/instrumentation-scope/index.md +++ b/content/en/docs/concepts/instrumentation-scope/index.md @@ -1,36 +1,35 @@ --- -title: Instrumentation Scope +title: Instrumentation scope weight: 80 --- -The [Instrumentation Scope](/docs/specs/otel/glossary/#instrumentation-scope) +The [Instrumentation scope](/docs/specs/otel/glossary/#instrumentation-scope) represents a logical unit within the application code with which the emitted telemetry can be associated. -It is typically the developer’s choice to decide what denotes a reasonable -instrumentation scope, e.g. a module, a package or a class can be chosen as -instrumentation scope. In the case of a library or framework, it is a common -approach to use an identifier as scope that is unique to the library or -framework, such as a fully qualified name and version of the library or -framework. If the library itself does not have built-in OpenTelemetry -instrumentation, and an Instrumentation Library is used instead, it is -recommended to use the name and version of the Instrumentation Library as the -instrumentation scope. +Developers can decide what denotes a reasonable instrumentation scope. For +example, they can select a module, a package, or a class as the instrumentation +scope. In the case of a library or framework, a common approach is to use an +identifier as scope that is unique to the library or framework, such as a fully +qualified name and version of the library or framework. If the library itself +doesn't have built-in OpenTelemetry instrumentation, and an instrumentation +library is used instead, use the name and version of the instrumentation library +as the instrumentation scope. -The Instrumentation Scope is defined by a name and version pair when a Tracer, -Meter or Logger instance is obtained from a provider. Each span, metric or log -record created by the instance will be associated with the provided -Instrumentation Scope. +The instrumentation scope is defined by a name and version pair when a tracer, +meter or logger instance is obtained from a provider. Each span, metric, or log +record created by the instance is then associated with the provided +instrumentation scope. -In your observability backend, this allows you to slice and dice your telemetry -data by the Instrumentation Scope, e.g. to see which of your users are using +In your observability backend, scoping allows you to slice and dice your +telemetry data by scope, for example to see which of your users are using which version of a library and what the performance of that library version is or to pin point a problem to a specific module of your application. -The diagram below illustrates a trace with multiple instrumentation scopes. The -different scopes are represented by different colors: +The following diagram illustrates a trace with multiple instrumentation scopes. +The different scopes are represented by different colors: -- At the top the `/api/placeOrder` span is generated by the used HTTP framework +- At the top the `/api/placeOrder` span is generated by the used HTTP framework. - The spans in green (`CheckoutService::placeOrder`, `prepareOrderItems` and `checkout`) are application code, grouped by the `CheckoutService` class. - The spans for `CartService::getCart` and `ProductService::getProduct` are also diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 2d03c195c12e..dc5d3632c621 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -1,7 +1,7 @@ --- title: Baggage weight: 4 -description: Contextual information that is passed between signals +description: Contextual information that is passed between signals. --- In OpenTelemetry, Baggage is contextual information that’s passed between spans. diff --git a/content/en/docs/concepts/signals/logs.md b/content/en/docs/concepts/signals/logs.md index f8165e1400ad..c044175aa33d 100644 --- a/content/en/docs/concepts/signals/logs.md +++ b/content/en/docs/concepts/signals/logs.md @@ -1,6 +1,7 @@ --- title: Logs weight: 3 +description: A recording of an event. --- A **log** is a timestamped text record, either structured (recommended) or diff --git a/content/en/docs/concepts/signals/metrics.md b/content/en/docs/concepts/signals/metrics.md index b71438ae0d5c..4dc888a0f497 100644 --- a/content/en/docs/concepts/signals/metrics.md +++ b/content/en/docs/concepts/signals/metrics.md @@ -1,7 +1,7 @@ --- title: Metrics weight: 2 -description: A measurement captured at runtime +description: A measurement captured at runtime. --- A **metric** is a **measurement** of a service captured at runtime. The moment diff --git a/content/en/docs/concepts/signals/traces.md b/content/en/docs/concepts/signals/traces.md index 1ea0b8bc4e00..4cd461345940 100644 --- a/content/en/docs/concepts/signals/traces.md +++ b/content/en/docs/concepts/signals/traces.md @@ -2,7 +2,7 @@ title: Traces weight: 1 cSpell:ignore: Guten -description: Understand the full path through your distributed application. +description: The path of a request through your application. --- **Traces** give us the big picture of what happens when a request is made to an From 82b93340dbec873f58d0d5aa343259b5b9ca052d Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 10:33:29 +0200 Subject: [PATCH 06/10] Fix format --- content/en/docs/concepts/instrumentation-scope/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/concepts/instrumentation-scope/index.md b/content/en/docs/concepts/instrumentation-scope/index.md index 7d6e676d7528..25a328ab397b 100644 --- a/content/en/docs/concepts/instrumentation-scope/index.md +++ b/content/en/docs/concepts/instrumentation-scope/index.md @@ -22,9 +22,9 @@ record created by the instance is then associated with the provided instrumentation scope. In your observability backend, scoping allows you to slice and dice your -telemetry data by scope, for example to see which of your users are using -which version of a library and what the performance of that library version is -or to pin point a problem to a specific module of your application. +telemetry data by scope, for example to see which of your users are using which +version of a library and what the performance of that library version is or to +pin point a problem to a specific module of your application. The following diagram illustrates a trace with multiple instrumentation scopes. The different scopes are represented by different colors: From 41f85bfe78a0b5ffb1a943c20707b29631034609 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 11:10:23 +0200 Subject: [PATCH 07/10] Update content/en/docs/concepts/components.md Co-authored-by: Patrice Chalin --- content/en/docs/concepts/components.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/components.md b/content/en/docs/concepts/components.md index d9bd600f133e..2e0ee02371a5 100644 --- a/content/en/docs/concepts/components.md +++ b/content/en/docs/concepts/components.md @@ -15,8 +15,8 @@ OpenTelemetry is currently made up of several main components: - [Zero-Code Instrumentation](#zero-code-instrumentation) - [Resource Detectors](#resource-detectors) - [Cross Service Propagators](#cross-service-propagators) - - [Sampler](#samplers) -- [K8s operator](#kubernetes-operator) + - [Samplers](#samplers) +- [Kubernetes operator](#kubernetes-operator) - [Function as a Service assets](#function-as-a-service-assets) OpenTelemetry lets you replace the need for vendor-specific SDKs and tools for From 15637545b17f4058516b612198cdd807f0556e78 Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 11:10:30 +0200 Subject: [PATCH 08/10] Update content/en/docs/concepts/_index.md Co-authored-by: Patrice Chalin --- content/en/docs/concepts/_index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index 184ef117a9c2..e7995b18369a 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -6,5 +6,5 @@ aliases: [concepts/overview] weight: 2 --- -In this section you can learn about the data sources and key components of the -OpenTelemetry project. This can help you understand how OpenTelemetry works. +This section covers data sources and key components of the +OpenTelemetry project, which can help you understand how OpenTelemetry works. From 233b822dd52145e8aa5a5c41b21c6b85cf7f7b1c Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 11:15:32 +0200 Subject: [PATCH 09/10] Remove code font from links in glossary entries --- content/en/docs/concepts/_index.md | 4 +- content/en/docs/concepts/glossary.md | 130 +++++++++++++-------------- 2 files changed, 66 insertions(+), 68 deletions(-) diff --git a/content/en/docs/concepts/_index.md b/content/en/docs/concepts/_index.md index e7995b18369a..93e1e5df8d64 100644 --- a/content/en/docs/concepts/_index.md +++ b/content/en/docs/concepts/_index.md @@ -6,5 +6,5 @@ aliases: [concepts/overview] weight: 2 --- -This section covers data sources and key components of the -OpenTelemetry project, which can help you understand how OpenTelemetry works. +This section covers data sources and key components of the OpenTelemetry +project, which can help you understand how OpenTelemetry works. diff --git a/content/en/docs/concepts/glossary.md b/content/en/docs/concepts/glossary.md index 7ddedec757c1..c4c1e17f3d7b 100644 --- a/content/en/docs/concepts/glossary.md +++ b/content/en/docs/concepts/glossary.md @@ -16,17 +16,17 @@ This page captures terminology used in the project and what it means. The process of combining multiple measurements into exact or estimated statistics about the measurements that took place during an interval of time, -during program execution. Used by the [`Metric`](#metric) -[`Data Source`](#data-source). +during program execution. Used by the [Metric](#metric) +[Data Source](#data-source). ### **API** Application Programming Interface. In the OpenTelemetry project, used to define -how telemetry data is generated per [`Data source`](#data-source). +how telemetry data is generated per [Data source](#data-source). ### **Application** -One or more [`Services`](#service) designed for end users or other applications. +One or more [Services](#service) designed for end users or other applications. ### **APM** @@ -36,9 +36,9 @@ issues, alerting and tooling for finding the root cause. ### **Attribute** -OpenTelemetry term for [`Metadata`](#metadata). Adds key-value information to -the entity producing telemetry. Used across [`Signals`](#signal) and -[`Resources`](#resource). See [attribute spec][attribute]. +OpenTelemetry term for [Metadata](#metadata). Adds key-value information to the +entity producing telemetry. Used across [Signals](#signal) and +[Resources](#resource). See [attribute spec][attribute]. ### **Automatic instrumentation** @@ -48,16 +48,16 @@ examples include bytecode injection or monkey patching. ### **Baggage** -A mechanism for propagating [`Metadata`](#metadata) to help establish a causal +A mechanism for propagating [Metadata](#metadata) to help establish a causal relationship between events and services. See [baggage spec][baggage]. ### **Client library** -See [`Instrumented library`](#instrumented-library). +See [Instrumented library](#instrumented-library). ### **Client-side app** -A component of an [`Application`](#application) that is not running inside a +A component of an [Application](#application) that is not running inside a private infrastructure and is typically used directly by end-users. Examples of client-side apps are browser apps, mobile apps, and apps running on IoT devices. @@ -71,16 +71,15 @@ Also known as the OpenTelemetry Collector. More on the Collector ### **Contrib** -Several [`Instrumentation Libraries`](#instrumentation-library) and the -[`Collector`](#collector) offer a set of core capabilities as well as a -dedicated contrib repository for non-core capabilities including vendor -`Exporters`. +Several [Instrumentation Libraries](#instrumentation-library) and the +[Collector](#collector) offer a set of core capabilities as well as a dedicated +contrib repository for non-core capabilities including vendor `Exporters`. ### **Context propagation** -Allows all [`Data sources`](#data-source) to share an underlying context -mechanism for storing state and accessing data across the lifespan of a -[`Transaction`](#transaction). See [context propagation +Allows all [Data sources](#data-source) to share an underlying context mechanism +for storing state and accessing data across the lifespan of a +[Transaction](#transaction). See [context propagation spec][context propagation]. ### **DAG** @@ -89,17 +88,17 @@ spec][context propagation]. ### **Data source** -See [`Signal`](#signal) +See [Signal](#signal) ### **Dimension** -A term used specifically by [`Metrics`](#metric). See [`Attribute`](#attribute). +A term used specifically by [Metrics](#metric). See [Attribute](#attribute). ### **Distributed tracing** -Tracks the progression of a single [`Request`](#request), called a -[`Trace`](#trace), as it is handled by [`Services`](#service) that make up an -[`Application`](#application). A [`Distributed trace`](#distributed-tracing) +Tracks the progression of a single [Request](#request), called a +[Trace](#trace), as it is handled by [Services](#service) that make up an +[Application](#application). A [Distributed trace](#distributed-tracing) transverses process, network and security boundaries. See [Distributed tracing][distributed tracing]. @@ -112,7 +111,7 @@ some customizations. See [more][distribution]. ### **Event** Something that happened where representation depends on the -[`Data source`](#data-source). For example, [`Spans`](#span). +[Data source](#data-source). For example, [Spans](#span). ### **Exporter** @@ -121,15 +120,14 @@ pull-based. ### **Field** -A term used specifically by [`Log Records`](#log-record). -[`Metadata`](#metadata) can be added through defined fields, including -[`Attributes`](#attribute) and [`Resource`](#resource). Other fields may also be -considered `Metadata`, including severity and trace information. See the [field -spec][field]. +A term used specifically by [Log Records](#log-record). [Metadata](#metadata) +can be added through defined fields, including [Attributes](#attribute) and +[Resource](#resource). Other fields may also be considered `Metadata`, including +severity and trace information. See the [field spec][field]. ### **gRPC** -A high-performance, open source universal [`RPC`](#rpc) framework. More on gRPC +A high-performance, open source universal [RPC](#rpc) framework. More on gRPC [here](https://grpc.io). ### **HTTP** @@ -138,17 +136,17 @@ Short for [Hypertext Transfer Protocol][http]. ### **Instrumented library** -Denotes the [`Library`](#library) for which the telemetry signals -([`Traces`](#trace), [`Metrics`](#metric), [`Logs`](#log)) are gathered. See +Denotes the [Library](#library) for which the telemetry signals +([Traces](#trace), [Metrics](#metric), [Logs](#log)) are gathered. See [more][spec-instrumented-lib]. ### **Instrumentation library** -Denotes the [`Library`](#library) that provides the instrumentation for a given -[`Instrumented library`](#instrumented-library). -[`Instrumented library`](#instrumented-library) and -[`Instrumentation library`](#instrumentation-library) can be the same -[`Library`](#library) if it has built-in OpenTelemetry instrumentation. See [the +Denotes the [Library](#library) that provides the instrumentation for a given +[Instrumented library](#instrumented-library). +[Instrumented library](#instrumented-library) and +[Instrumentation library](#instrumentation-library) can be the same +[Library](#library) if it has built-in OpenTelemetry instrumentation. See [the lib specification][spec-instrumentation-lib]. ### **JSON** @@ -157,7 +155,7 @@ Short for [JavaScript Object Notation][json]. ### **Label** -A term used specifically by [`Metrics`](#metric). See [`Metadata`](#metadata). +A term used specifically by [Metrics](#metric). See [Metadata](#metadata). ### **Language** @@ -169,32 +167,32 @@ A language-specific collection of behavior invoked by an interface. ### **Log** -Sometimes used to refer to a collection of [`Log records`](#log-record). Can be -ambiguous since people also sometimes use [`Log`](#log) to refer to a single -[`Log record`](#log-record). Where ambiguity is possible, use additional +Sometimes used to refer to a collection of [Log records](#log-record). Can be +ambiguous since people also sometimes use [Log](#log) to refer to a single +[Log record](#log-record). Where ambiguity is possible, use additional qualifiers, for example, `Log record`. See [more][log] ### **Log record** -A recording of an [`Event`](#event). Typically. the record includes a timestamp -indicating when the [`Event`](#event) happened as well as other data that +A recording of an [Event](#event). Typically. the record includes a timestamp +indicating when the [Event](#event) happened as well as other data that describes what happened, where it happened, and so on. See [more][log record]. ### **Metadata** A key-value pair, for example `foo="bar"`, added to an entity producing -telemetry. OpenTelemetry calls these pairs [`Attributes`](#attribute). In -addition, [`Metrics`](#metric) have [`Dimensions`](#dimension) an -[`Labels`](#label), while [`Logs`](#log) have [`Fields`](#field). +telemetry. OpenTelemetry calls these pairs [Attributes](#attribute). In +addition, [Metrics](#metric) have [Dimensions](#dimension) an [Labels](#label), +while [Logs](#log) have [Fields](#field). ### **Metric** Records a data point, either raw measurements or predefined aggregation, as time -series with [`Metadata`](#metadata). See [more][metric]. +series with [Metadata](#metadata). See [more][metric]. ### **OC** -Short form for [`OpenCensus`](#opencensus). +Short form for [OpenCensus](#opencensus). ### **OpenCensus** @@ -212,7 +210,7 @@ Vendor-neutral APIs and instrumentation for distributed tracing. ### **OT** -Short form for [`OpenTracing`](#opentracing). +Short form for [OpenTracing](#opentracing). ### **OTel** @@ -229,7 +227,7 @@ Short for [OpenTelemetry Protocol](/docs/specs/otlp/). ### **Propagators** Used to serialize and deserialize specific parts of telemetry data such as span -context and [`Baggage`](#baggage) in [`Spans`](#span). See [more][propagators]. +context and [Baggage](#baggage) in [Spans](#span). See [more][propagators]. ### **Proto** @@ -237,18 +235,18 @@ Language independent interface types. See [more][proto]. ### **Receiver** -The term used by the [`Collector`](/docs/collector/configuration/#receivers) to +The term used by the [Collector](/docs/collector/configuration/#receivers) to define how telemetry data is received. Receivers can be push- or pull-based. See [more][receiver]. ### **Request** -See [`Distributed Tracing`](#distributed-tracing). +See [Distributed Tracing](#distributed-tracing). ### **Resource** Captures information about the entity producing telemetry as -[`Attributes`](#attribute). For example, a process producing telemetry that is +[Attributes](#attribute). For example, a process producing telemetry that is running in a container on Kubernetes has a process name, a pod name, a namespace, and possibly a deployment name. All these attributes can be included in the `Resource`. @@ -264,32 +262,32 @@ Short for [Remote Procedure Call][rpc]. ### **Sampling** A mechanism to control the amount of data exported. Most commonly used with the -[`Tracing`](#trace) [`Data Source`](#data-source). See [more][sampling]. +[Tracing](#trace) [Data Source](#data-source). See [more][sampling]. ### **SDK** Short for Software Development Kit. Refers to a telemetry SDK that denotes a -[`Library`](#library) that implement the OpenTelemetry [`API`](#api). +[Library](#library) that implement the OpenTelemetry [API](#api). ### **Semantic conventions** -Defines standard names and values of [`Metadata`](#metadata) in order to provide +Defines standard names and values of [Metadata](#metadata) in order to provide vendor-agnostic telemetry data. ### **Service** -A component of an [`Application`](#application). Multiple instances of a -[`Service`](#service) are typically deployed for high availability and -scalability. A [`Service`](#service) can be deployed in multiple locations. +A component of an [Application](#application). Multiple instances of a +[Service](#service) are typically deployed for high availability and +scalability. A [Service](#service) can be deployed in multiple locations. ### **Signal** -One of [`Traces`](#trace), [`Metrics`](#metric) or [`Logs`](#log). More on -Signals [here][signals]. +One of [Traces](#trace), [Metrics](#metric) or [Logs](#log). More on Signals +[here][signals]. ### **Span** -Represents a single operation within a [`Trace`](#trace). See [more][span]. +Represents a single operation within a [Trace](#trace). See [more][span]. ### **Span link** @@ -309,20 +307,20 @@ occurred. See [more][status]. ### **Tag** -See [`Metadata`](#metadata). +See [Metadata](#metadata). ### **Trace** -A [`DAG`](#dag) of [`Spans`](#span), where the edges between [`Spans`](#span) -are defined as parent-child relationship. See [more][trace]. +A [DAG](#dag) of [Spans](#span), where the edges between [Spans](#span) are +defined as parent-child relationship. See [more][trace]. ### **Tracer** -Responsible for creating [`Spans`](#span). See [more][tracer]. +Responsible for creating [Spans](#span). See [more][tracer]. ### **Transaction** -See [`Distributed Tracing`](#distributed-tracing). +See [Distributed Tracing](#distributed-tracing). ### **zPages** From bb9ce2702748e2c4a9952c52074cf660ba92c69f Mon Sep 17 00:00:00 2001 From: Fabrizio Ferri-Benedetti Date: Tue, 28 May 2024 11:30:56 +0200 Subject: [PATCH 10/10] Capitalization fix --- content/en/docs/concepts/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/concepts/glossary.md b/content/en/docs/concepts/glossary.md index c4c1e17f3d7b..866aafd1645e 100644 --- a/content/en/docs/concepts/glossary.md +++ b/content/en/docs/concepts/glossary.md @@ -17,7 +17,7 @@ This page captures terminology used in the project and what it means. The process of combining multiple measurements into exact or estimated statistics about the measurements that took place during an interval of time, during program execution. Used by the [Metric](#metric) -[Data Source](#data-source). +[Data source](#data-source). ### **API**