From 0bc89e63307857b79131f6ebeaebb3ca27c62d00 Mon Sep 17 00:00:00 2001 From: leandrocarpenter Date: Tue, 6 Aug 2024 22:54:26 -0300 Subject: [PATCH 1/4] primeiro commit --- content/pt/docs/concepts/signals/_index.md | 30 ++ content/pt/docs/concepts/signals/baggage.md | 79 ++++ content/pt/docs/concepts/signals/logs.md | 244 ++++++++++++ content/pt/docs/concepts/signals/metrics.md | 122 ++++++ content/pt/docs/concepts/signals/traces.md | 388 ++++++++++++++++++++ 5 files changed, 863 insertions(+) create mode 100644 content/pt/docs/concepts/signals/_index.md create mode 100644 content/pt/docs/concepts/signals/baggage.md create mode 100644 content/pt/docs/concepts/signals/logs.md create mode 100644 content/pt/docs/concepts/signals/metrics.md create mode 100644 content/pt/docs/concepts/signals/traces.md diff --git a/content/pt/docs/concepts/signals/_index.md b/content/pt/docs/concepts/signals/_index.md new file mode 100644 index 000000000000..d5a38b4c874e --- /dev/null +++ b/content/pt/docs/concepts/signals/_index.md @@ -0,0 +1,30 @@ +--- +title: Sinais +description: Aprenda sobre a categorias de telemetria suportadas pelo OpenTelemetry. +aliases: + - /docs/concepts/data-sources + - /docs/concepts/otel-concepts +weight: 11 +default_lang_commit: 08e13eb62f2869300301670675969be705db59ae +--- + +O objetivo do OpenTelemetry é colletar, processar e exportar **[signals][]**. +Sinais são saídas de sistemas que descrevem atividades fundamentais do +sistema operacional e aplicações em execução na plataforma. Um sinal pode +ser alguma coisa que você quer avaliar em algum ponto específico do tempo, +como temperatura, memória utilizada, ou um evento que passa por um componente +de +something you want to measure at a specific point in time, like temperature or +memory usage, or an event that goes through the components of your distributed +system that you'd like to trace. You can group different signals together to +observe the inner workings of the same piece of technology under different +angles. + +OpenTelemetry currently supports [traces](/docs/concepts/signals/traces), +[metrics](/docs/concepts/signals/metrics), [logs](/docs/concepts/signals/logs) +and [baggage](/docs/concepts/signals/baggage). _Events_ are a specific type of +log, and +[_profiles_ are being worked on](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md) +by the Profiling Working Group. + +[signals]: /docs/specs/otel/glossary/#signals diff --git a/content/pt/docs/concepts/signals/baggage.md b/content/pt/docs/concepts/signals/baggage.md new file mode 100644 index 000000000000..7cf6d1379fce --- /dev/null +++ b/content/pt/docs/concepts/signals/baggage.md @@ -0,0 +1,79 @@ +--- +title: Baggage +weight: 4 +description: Contextual information that is passed between signals. +--- + +In OpenTelemetry, Baggage is contextual information that resides next to +context. Baggage is a key-value store, which means it lets you +[propagate](/docs/concepts/context-propagation/#propagation) any data you like +alongside [context](/docs/concepts/context-propagation/#context). + +Baggage means you can pass data across services and processes, making it +available to add to [traces](/docs/concepts/signals/traces/), +[metrics](/docs/concepts/signals/metrics/), or +[logs](/docs/concepts/signals/logs/) in those services. + +## Example + +Baggage is often used in tracing to propagate additional data across services. + +For example, imagine you have a `clientId` at the start of a request, but you'd +like for that ID to be available on all spans in a trace, some metrics in +another service, and some logs along the way. Because the trace may span +multiple services, you need some way to propagate that data without copying the +`clientId` across many places in your codebase. + +By using +[Context Propagation](/docs/concepts/signals/traces/#context-propagation) to +pass baggage across these services, the `clientId` is available to add to any +additional spans, metrics, or logs. Additionally, instrumentations automatically +propagate baggage for you. + +![OTel Baggage](/img/otel-baggage.svg) + +## What should OTel Baggage be used for? + +Baggage is best used to include information typically available only at the +start of a request further downstream. This can include things like Account +Identification, User IDs, Product IDs, and origin IPs, for example. + +Propagating this information using baggage allows for deeper analysis of +telemetry in a backend. For example, if you include information like a User ID +on a span that tracks a database call, you can much more easily answer questions +like "which users are experiencing the slowest database calls?" You can also log +information about a downstream operation and include that same User ID in the +log data. + +![OTel Baggage](/img/otel-baggage-2.svg) + +## Baggage security considerations + +Sensitive Baggage items can be shared with unintended resources, like +third-party APIs. This is because automatic instrumentation includes Baggage in +most of your service’s network requests. Specifically, Baggage and other parts +of trace context are sent in HTTP headers, making it visible to anyone +inspecting your network traffic. If traffic is restricted within your network, +then this risk may not apply, but keep in mind that downstream services could +propagate Baggage outside your network. + +Also, there are no built-in integrity checks to ensure that Baggage items are +yours, so exercise caution when reading them. + +## Baggage is not the same as attributes + +An important thing to note about baggage is that it is a separate key-value +store and is unassociated with attributes on spans, metrics, or logs without +explicitly adding them. + +To add baggage entries to attributes, you need to explicitly read the data from +baggage and add it as attributes to your spans, metrics, or logs. + +Because a common use cases for Baggage is to add data to +[Span Attributes](/docs/concepts/signals/traces/#attributes) across a whole +trace, several languages have Baggage Span Processors that add data from baggage +as attributes on span creation. + +> For more information, see the [baggage specification][]. + +[baggage specification]: /docs/specs/otel/overview/#baggage-signal diff --git a/content/pt/docs/concepts/signals/logs.md b/content/pt/docs/concepts/signals/logs.md new file mode 100644 index 000000000000..b4ee3c84b3d0 --- /dev/null +++ b/content/pt/docs/concepts/signals/logs.md @@ -0,0 +1,244 @@ +--- +title: Logs +description: A recording of an event. +weight: 3 +cSpell:ignore: filelogreceiver semistructured transformprocessor +--- + +A **log** is a timestamped text record, either structured (recommended) or +unstructured, with optional metadata. Of all telemetry signals, logs have the +biggest legacy. Most programming languages have built-in logging capabilities or +well-known, widely used logging libraries. + +## OpenTelemetry logs + +OpenTelemetry does not define a bespoke API or SDK to create logs. Instead, +OpenTelemetry logs are the existing logs you already have from a logging +framework or infrastructure component. OpenTelemetry SDKs and +autoinstrumentation utilize several components to automatically correlate logs +with [traces](/docs/concepts/signals/traces). + +OpenTelemetry's support for logs is designed to be fully compatible with what +you already have, providing capabilities to wrap those logs with additional +context and a common toolkit to parse and manipulate logs into a common format +across many different sources. + +### OpenTelemetry logs in the OpenTelemetry Collector + +The [OpenTelemetry Collector](/docs/collector) provides several tools to work +with logs: + +- Several receivers which parse logs from specific, known sources of log data. +- The `filelogreceiver`, which reads logs from any file and provides features to + parse them from different formats or use a regular expression. +- Processors like the `transformprocessor` which lets you parse nested data, + flatten nested structures, add/remove/update values, and more. +- Exporters that let you emit log data in a non-OpenTelemetry format. + +The first step in adopting OpenTelemetry frequently involves deploying a +Collector as a general-purposes logging agent. + +### OpenTelemetry logs for applications + +In applications, OpenTelemetry logs are created with any logging library or +built-in logging capabilities. When you add autoinstrumentation or activate an +SDK, OpenTelemetry will automatically correlate your existing logs with any +active trace and span, wrapping the log body with their IDs. In other words, +OpenTelemetry automatically correlates your logs and traces. + +### Language support + +Logs are a [stable](/docs/specs/otel/versioning-and-stability/#stable) signal in +the OpenTelemetry specification. For the individual language specific +implementations of the Logs API & SDK, the status is as follows: + +{{% signal-support-table "logs" %}} + +## Structured, unstructured, and semistructured logs + +OpenTelemetry does not technically distinguish between structured and +unstructured logs. You can use any log you have with OpenTelemetry. However, not +all log formats are equally useful! Structured logs, in particular, are +recommended for production observability because they are easy to parse and +analyze at scale. The following section explains the differences between +structured, unstructured, and semistructured logs. + +### Structured logs + +A structured log is a log whose textual format follows a consistent, +machine-readable format. For applications, one of the most common formats is +JSON: + +```json +{ + "timestamp": "2024-08-04T12:34:56.789Z", + "level": "INFO", + "service": "user-authentication", + "environment": "production", + "message": "User login successful", + "context": { + "userId": "12345", + "username": "johndoe", + "ipAddress": "192.168.1.1", + "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" + }, + "transactionId": "abcd-efgh-ijkl-mnop", + "duration": 200, + "request": { + "method": "POST", + "url": "/api/v1/login", + "headers": { + "Content-Type": "application/json", + "Accept": "application/json" + }, + "body": { + "username": "johndoe", + "password": "******" + } + }, + "response": { + "statusCode": 200, + "body": { + "success": true, + "token": "jwt-token-here" + } + } +} +``` + +and for infrastructure components, Common Log Format (CLF) is commonly used: + +```text +127.0.0.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234 +``` + +It is also common to have different structured log formats mixed together. For +example, an Extended Log Format (ELF) log can mix JSON with the +whitespace-separated data in a CLF log. + +```text +192.168.1.1 - johndoe [04/Aug/2024:12:34:56 -0400] "POST /api/v1/login HTTP/1.1" 200 1234 "http://example.com" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" {"transactionId": "abcd-efgh-ijkl-mnop", "responseTime": 150, "requestBody": {"username": "johndoe"}, "responseHeaders": {"Content-Type": "application/json"}} +``` + +To make the most use of this log, parse both the JSON and the ELF-related pieces +into a shared format to make analysis on an observability backend easier. The +`filelogreceiver` in the [OpenTelemetry Collector](/docs/collector) contains +standardized ways to parse logs like this. + +Structured logs are the preferred way to use logs. Because structured logs are +emitted in a consistent format, they are straightforward to parse, which makes +them easier to preprocess in an OpenTelemetry Collector, correlate with other +data, and ultimate analyze in an Observability backend. + +### Unstructured logs + +Unstructured logs are logs that don't follow a consistent structure. They may be +more human-readable, and are often used in development. However, it is not +preferred to use unstructured logs for production observability purposes, since +they are much more difficult to parse and analyze at scale. + +Examples of unstructured logs: + +```text +[ERROR] 2024-08-04 12:45:23 - Failed to connect to database. Exception: java.sql.SQLException: Timeout expired. Attempted reconnect 3 times. Server: db.example.com, Port: 5432 + +System reboot initiated at 2024-08-04 03:00:00 by user: admin. Reason: Scheduled maintenance. Services stopped: web-server, database, cache. Estimated downtime: 15 minutes. + +DEBUG - 2024-08-04 09:30:15 - User johndoe performed action: file_upload. Filename: report_Q3_2024.pdf, Size: 2.3 MB, Duration: 5.2 seconds. Result: Success +``` + +It is possible to store and analyze Unstructured logs in production, although +you may need to do substantial work to parse or otherwise pre-process them to be +machine-readable. For example, the above three logs will require a regular +expression to parse their timestamps and custom parsers to consistently extract +the bodies of the log message. This will typically be necessary for a logging +backend to know how to sort and organize the logs by timestamp. Although it's +possible to parse unstructured logs for analysis purposes, doing this may be +more work than switching to structured logging, such as via a standard logging +framework in your applications. + +### Semistructured logs + +A semistructured log is a log that does use some self-consistent patterns to +distinguish data so that it's machine-readable, but may not use the same +formatting and delimiters between data across different systems. + +Example of a semistructured log: + +```text +2024-08-04T12:45:23Z level=ERROR service=user-authentication userId=12345 action=login message="Failed login attempt" error="Invalid password" ipAddress=192.168.1.1 userAgent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36" +``` + +Although machine-readable, semistructured logs may require several different +parsers to allow for analysis at scale. + +## OpenTelemetry logging components + +The following lists of concepts and components power OpenTelemetry's logging +support. + +### Log Appender / Bridge + +As an application developer, the **Logs Bridge API** should not be called by you +directly, as it is provided for logging library authors to build log appenders / +bridges. Instead, you just use your preferred logging library and configure it +to use a log appender (or log bridge) that is able to emit logs into an +OpenTelemetry LogRecordExporter. + +OpenTelemetry language SDKs offer this functionality. + +### Logger Provider + +> Part of the **Logs Bridge API** and should only be used if you are the author +> of a logging library. + +A Logger Provider (sometimes called `LoggerProvider`) is a factory for +`Logger`s. In most cases, the Logger Provider is initialized once and its +lifecycle matches the application's lifecycle. Logger Provider initialization +also includes Resource and Exporter initialization. + +### Logger + +> Part of the **Logs Bridge API** and should only be used if you are the author +> of a logging library. + +A Logger creates log records. Loggers are created from Log Providers. + +### Log Record Exporter + +Log Record Exporters send log records to a consumer. This consumer can be +standard output for debugging and development-time, the OpenTelemetry Collector, +or any open source or vendor backend of your choice. + +### Log Record + +A log record represents the recording of an event. In OpenTelemetry a log record +contains two kinds of fields: + +- Named top-level fields of specific type and meaning +- Resource and attributes fields of arbitrary value and type + +The top-level fields are: + +| Field Name | Description | +| -------------------- | -------------------------------------------- | +| Timestamp | Time when the event occurred. | +| ObservedTimestamp | Time when the event was observed. | +| TraceId | Request trace ID. | +| SpanId | Request span ID. | +| TraceFlags | W3C trace flag. | +| SeverityText | The severity text (also known as log level). | +| SeverityNumber | Numerical value of the severity. | +| Body | The body of the log record. | +| Resource | Describes the source of the log. | +| InstrumentationScope | Describes the scope that emitted the log. | +| Attributes | Additional information about the event. | + +For more details on log records and log fields, see +[Logs Data Model](/docs/specs/otel/logs/data-model/). + +### Specification + +To learn more about logs in OpenTelemetry, see the [logs specification][]. + +[logs specification]: /docs/specs/otel/overview/#log-signal diff --git a/content/pt/docs/concepts/signals/metrics.md b/content/pt/docs/concepts/signals/metrics.md new file mode 100644 index 000000000000..8e64ae9d86a7 --- /dev/null +++ b/content/pt/docs/concepts/signals/metrics.md @@ -0,0 +1,122 @@ +--- +title: Metrics +weight: 2 +description: A measurement captured at runtime. +--- + +A **metric** is a **measurement** of a service captured at runtime. The moment +of capturing a measurements is known as a **metric event**, which consists not +only of the measurement itself, but also the time at which it was captured and +associated metadata. + +Application and request metrics are important indicators of availability and +performance. Custom metrics can provide insights into how availability +indicators impact user experience or the business. Collected data can be used to +alert of an outage or trigger scheduling decisions to scale up a deployment +automatically upon high demand. + +To understand how metrics in OpenTelemetry works, let's look at a list of +components that will play a part in instrumenting our code. + +## Meter Provider + +A Meter Provider (sometimes called `MeterProvider`) is a factory for `Meter`s. +In most applications, a Meter Provider is initialized once and its lifecycle +matches the application's lifecycle. Meter Provider initialization also includes +Resource and Exporter initialization. It is typically the first step in metering +with OpenTelemetry. In some language SDKs, a global Meter Provider is already +initialized for you. + +## Meter + +A Meter creates [metric instruments](#metric-instruments), capturing +measurements about a service at runtime. Meters are created from Meter +Providers. + +## Metric Exporter + +Metric Exporters send metric data to a consumer. This consumer can be standard +output for debugging during development, the OpenTelemetry Collector, or any +open source or vendor backend of your choice. + +## Metric Instruments + +In OpenTelemetry measurements are captured by **metric instruments**. A metric +instrument is defined by: + +- Name +- Kind +- Unit (optional) +- Description (optional) + +The name, unit, and description are chosen by the developer or defined via +[semantic conventions](/docs/specs/semconv/general/metrics/) for common ones +like request and process metrics. + +The instrument kind is one of the following: + +- **Counter**: A value that accumulates over time -- you can think of this like + an odometer on a car; it only ever goes up. +- **Asynchronous Counter**: Same as the **Counter**, but is collected once for + each export. Could be used if you don't have access to the continuous + increments, but only to the aggregated value. +- **UpDownCounter**: A value that accumulates over time, but can also go down + again. An example could be a queue length, it will increase and decrease with + the number of work items in the queue. +- **Asynchronous UpDownCounter**: Same as the **UpDownCounter**, but is + collected once for each export. Could be used if you don't have access to the + continuous changes, but only to the aggregated value (e.g., current queue + size). +- **Gauge**: Measures a current value at the time it is read. An example would + be the fuel gauge in a vehicle. Gauges are asynchronous. +- **Histogram**: A client-side aggregation of values, such as request latencies. + A histogram is a good choice if you are interested in value statistics. For + example: How many requests take fewer than 1s? + +For more on synchronous and asynchronous instruments, and which kind is best +suited for your use case, see +[Supplementary Guidelines](/docs/specs/otel/metrics/supplementary-guidelines/). + +## Aggregation + +In addition to the metric instruments, the concept of **aggregations** is an +important one to understand. An aggregation is a technique whereby a large +number of measurements are combined into either exact or estimated statistics +about metric events that took place during a time window. The OTLP protocol +transports such aggregated metrics. The OpenTelemetry API provides a default +aggregation for each instrument which can be overridden using the Views. The +OpenTelemetry project aims to provide default aggregations that are supported by +visualizers and telemetry backends. + +Unlike [request tracing](/docs/concepts/signals/traces/), which is intended to +capture request lifecycles and provide context to the individual pieces of a +request, metrics are intended to provide statistical information in aggregate. +Some examples of use cases for metrics include: + +- Reporting the total number of bytes read by a service, per protocol type. +- Reporting the total number of bytes read and the bytes per request. +- Reporting the duration of a system call. +- Reporting request sizes in order to determine a trend. +- Reporting CPU or memory usage of a process. +- Reporting average balance values from an account. +- Reporting current active requests being handled. + +## Views + +A view provides SDK users with the flexibility to customize the metrics output +by the SDK. You can customize which metric instruments are to be processed or +ignored. You can also customize aggregation and what attributes you want to +report on metrics. + +## Language Support + +Metrics are a [stable](/docs/specs/otel/versioning-and-stability/#stable) signal +in the OpenTelemetry specification. For the individual language specific +implementations of the Metrics API & SDK, the status is as follows: + +{{% signal-support-table "metrics" %}} + +## Specification + +To learn more about metrics in OpenTelemetry, see the +[metrics specification](/docs/specs/otel/overview/#metric-signal). diff --git a/content/pt/docs/concepts/signals/traces.md b/content/pt/docs/concepts/signals/traces.md new file mode 100644 index 000000000000..4cd461345940 --- /dev/null +++ b/content/pt/docs/concepts/signals/traces.md @@ -0,0 +1,388 @@ +--- +title: Traces +weight: 1 +cSpell:ignore: Guten +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 +application. Whether your application is a monolith with a single database or a +sophisticated mesh of services, traces are essential to understanding the full +"path" a request takes in your application. + +Let's explore this with three units of work, represented as [Spans](#spans): + +{{% alert title="Note" %}} + +The following JSON examples do not represent a specific format, and especially +not [OTLP/JSON](/docs/specs/otlp/#json-protobuf-encoding), which is more +verbose. + +{{% /alert %}} + +`hello` span: + +```json +{ + "name": "hello", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x051581bf3cb55c13" + }, + "parent_id": null, + "start_time": "2022-04-29T18:52:58.114201Z", + "end_time": "2022-04-29T18:52:58.114687Z", + "attributes": { + "http.route": "some_route1" + }, + "events": [ + { + "name": "Guten Tag!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +This is the root span, denoting the beginning and end of the entire operation. +Note that it has a `trace_id` field indicating the trace, but has no +`parent_id`. That's how you know it's the root span. + +`hello-greetings` span: + +```json +{ + "name": "hello-greetings", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x5fb397be34d26b51" + }, + "parent_id": "0x051581bf3cb55c13", + "start_time": "2022-04-29T18:52:58.114304Z", + "end_time": "2022-04-29T22:52:58.114561Z", + "attributes": { + "http.route": "some_route2" + }, + "events": [ + { + "name": "hey there!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + }, + { + "name": "bye now!", + "timestamp": "2022-04-29T18:52:58.114585Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +This span encapsulates specific tasks, like saying greetings, and its parent is +the `hello` span. Note that it shares the same `trace_id` as the root span, +indicating it's a part of the same trace. Additionally, it has a `parent_id` +that matches the `span_id` of the `hello` span. + +`hello-salutations` span: + +```json +{ + "name": "hello-salutations", + "context": { + "trace_id": "0x5b8aa5a2d2c872e8321cf37308d69df2", + "span_id": "0x93564f51e1abe1c2" + }, + "parent_id": "0x051581bf3cb55c13", + "start_time": "2022-04-29T18:52:58.114492Z", + "end_time": "2022-04-29T18:52:58.114631Z", + "attributes": { + "http.route": "some_route3" + }, + "events": [ + { + "name": "hey there!", + "timestamp": "2022-04-29T18:52:58.114561Z", + "attributes": { + "event_attributes": 1 + } + } + ] +} +``` + +This span represents the third operation in this trace and, like the previous +one, it's a child of the `hello` span. That also makes it a sibling of the +`hello-greetings` span. + +These three blocks of JSON all share the same `trace_id`, and the `parent_id` +field represents a hierarchy. That makes it a Trace! + +Another thing you'll note is that each Span looks like a structured log. That's +because it kind of is! One way to think of Traces is that they're a collection +of structured logs with context, correlation, hierarchy, and more baked in. +However, these "structured logs" can come from different processes, services, +VMs, data centers, and so on. This is what allows tracing to represent an +end-to-end view of any system. + +To understand how tracing in OpenTelemetry works, let's look at a list of +components that will play a part in instrumenting our code. + +## Tracer Provider + +A Tracer Provider (sometimes called `TracerProvider`) is a factory for +`Tracer`s. In most applications, a Tracer Provider is initialized once and its +lifecycle matches the application's lifecycle. Tracer Provider initialization +also includes Resource and Exporter initialization. It is typically the first +step in tracing with OpenTelemetry. In some language SDKs, a global Tracer +Provider is already initialized for you. + +## Tracer + +A Tracer creates spans containing more information about what is happening for a +given operation, such as a request in a service. Tracers are created from Tracer +Providers. + +## Trace Exporters + +Trace Exporters send traces to a consumer. This consumer can be standard output +for debugging and development-time, the OpenTelemetry Collector, or any open +source or vendor backend of your choice. + +## Context Propagation + +Context Propagation is the core concept that enables Distributed Tracing. With +Context Propagation, Spans can be correlated with each other and assembled into +a trace, regardless of where Spans are generated. To learn more about this +topic, see the concept page on +[Context Propagation](/docs/concepts/context-propagation). + +## Spans + +A **span** represents a unit of work or operation. Spans are the building blocks +of Traces. In OpenTelemetry, they include the following information: + +- Name +- Parent span ID (empty for root spans) +- Start and End Timestamps +- [Span Context](#span-context) +- [Attributes](#attributes) +- [Span Events](#span-events) +- [Span Links](#span-links) +- [Span Status](#span-status) + +Sample span: + +```json +{ + "name": "/v1/sys/health", + "context": { + "trace_id": "7bba9f33312b3dbb8b2c2c62bb7abe2d", + "span_id": "086e83747d0e381e" + }, + "parent_id": "", + "start_time": "2021-10-22 16:04:01.209458162 +0000 UTC", + "end_time": "2021-10-22 16:04:01.209514132 +0000 UTC", + "status_code": "STATUS_CODE_OK", + "status_message": "", + "attributes": { + "net.transport": "IP.TCP", + "net.peer.ip": "172.17.0.1", + "net.peer.port": "51820", + "net.host.ip": "10.177.2.152", + "net.host.port": "26040", + "http.method": "GET", + "http.target": "/v1/sys/health", + "http.server_name": "mortar-gateway", + "http.route": "/v1/sys/health", + "http.user_agent": "Consul Health Check", + "http.scheme": "http", + "http.host": "10.177.2.152:26040", + "http.flavor": "1.1" + }, + "events": [ + { + "name": "", + "message": "OK", + "timestamp": "2021-10-22 16:04:01.209512872 +0000 UTC" + } + ] +} +``` + +Spans can be nested, as is implied by the presence of a parent span ID: child +spans represent sub-operations. This allows spans to more accurately capture the +work done in an application. + +### Span Context + +Span context is an immutable object on every span that contains the following: + +- The Trace ID representing the trace that the span is a part of +- The span's Span ID +- Trace Flags, a binary encoding containing information about the trace +- Trace State, a list of key-value pairs that can carry vendor-specific trace + information + +Span context is the part of a span that is serialized and propagated alongside +[Distributed Context](#context-propagation) and +[Baggage](/docs/concepts/signals/baggage). + +Because Span Context contains the Trace ID, it is used when creating +[Span Links](#span-links). + +### Attributes + +Attributes are key-value pairs that contain metadata that you can use to +annotate a Span to carry information about the operation it is tracking. + +For example, if a span tracks an operation that adds an item to a user's +shopping cart in an eCommerce system, you can capture the user's ID, the ID of +the item to add to the cart, and the cart ID. + +You can add attributes to spans during or after span creation. Prefer adding +attributes at span creation to make the attributes available to SDK sampling. If +you have to add a value after span creation, update the span with the value. + +Attributes have the following rules that each language SDK implements: + +- Keys must be non-null string values +- Values must be a non-null string, boolean, floating point value, integer, or + an array of these values + +Additionally, there are +[Semantic Attributes](/docs/specs/semconv/general/trace/), which are known +naming conventions for metadata that is typically present in common operations. +It's helpful to use semantic attribute naming wherever possible so that common +kinds of metadata are standardized across systems. + +### Span Events + +A Span Event can be thought of as a structured log message (or annotation) on a +Span, typically used to denote a meaningful, singular point in time during the +Span's duration. + +For example, consider two scenarios in a web browser: + +1. Tracking a page load +2. Denoting when a page becomes interactive + +A Span is best used to the first scenario because it's an operation with a start +and an end. + +A Span Event is best used to track the second scenario because it represents a +meaningful, singular point in time. + +#### When to use span events versus span attributes + +Since span events also contain attributes, the question of when to use events +instead of attributes might not always have an obvious answer. To inform your +decision, consider whether a specific timestamp is meaningful. + +For example, when you're tracking an operation with a span and the operation +completes, you might want to add data from the operation to your telemetry. + +- If the timestamp in which the operation completes is meaningful or relevant, + attach the data to a span event. +- If the timestamp isn't meaningful, attach the data as span attributes. + +### Span Links + +Links exist so that you can associate one span with one or more spans, implying +a causal relationship. For example, let’s say we have a distributed system where +some operations are tracked by a trace. + +In response to some of these operations, an additional operation is queued to be +executed, but its execution is asynchronous. We can track this subsequent +operation with a trace as well. + +We would like to associate the trace for the subsequent operations with the +first trace, but we cannot predict when the subsequent operations will start. We +need to associate these two traces, so we will use a span link. + +You can link the last span from the first trace to the first span in the second +trace. Now, they are causally associated with one another. + +Links are optional but serve as a good way to associate trace spans with one +another. + +### Span Status + +Each span has a status. The three possible values are: + +- `Unset` +- `Error` +- `Ok` + +The default value is `Unset`. A span status that is `Unset` means that the +operation it tracked successfully completed without an error. + +When a span status is `Error`, then that means some error occurred in the +operation it tracks. For example, this could be due to an HTTP 500 error on a +server handling a request. + +When a span status is `Ok`, then that means the span was explicitly marked as +error-free by the developer of an application. Although this is unintuitive, +it's not required to set a span status as `Ok` when a span is known to have +completed without error, as this is covered by `Unset`. What `Ok` does is +represent an unambiguous "final call" on the status of a span that has been +explicitly set by a user. This is helpful in any situation where a developer +wishes for there to be no other interpretation of a span other than +"successful". + +To reiterate: `Unset` represents a span that completed without an error. `Ok` +represents when a developer explicitly marks a span as successful. In most +cases, it is not necessary to explicitly mark a span as `Ok`. + +### Span Kind + +When a span is created, it is one of `Client`, `Server`, `Internal`, `Producer`, +or `Consumer`. This span kind provides a hint to the tracing backend as to how +the trace should be assembled. According to the OpenTelemetry specification, the +parent of a server span is often a remote client span, and the child of a client +span is usually a server span. Similarly, the parent of a consumer span is +always a producer and the child of a producer span is always a consumer. If not +provided, the span kind is assumed to be internal. + +For more information regarding SpanKind, see +[SpanKind](/docs/specs/otel/trace/api/#spankind). + +#### Client + +A client span represents a synchronous outgoing remote call such as an outgoing +HTTP request or database call. Note that in this context, "synchronous" does not +refer to `async/await`, but to the fact that it is not queued for later +processing. + +#### Server + +A server span represents a synchronous incoming remote call such as an incoming +HTTP request or remote procedure call. + +#### Internal + +Internal spans represent operations which do not cross a process boundary. +Things like instrumenting a function call or an Express middleware may use +internal spans. + +#### Producer + +Producer spans represent the creation of a job which may be asynchronously +processed later. It may be a remote job such as one inserted into a job queue or +a local job handled by an event listener. + +#### Consumer + +Consumer spans represent the processing of a job created by a producer and may +start long after the producer span has already ended. + +## Specification + +For more information, see the +[traces specification](/docs/specs/otel/overview/#tracing-signal). From f5c96e04cf8dc97e325c5786607dda1ff5b34cea Mon Sep 17 00:00:00 2001 From: leandrocarpenter Date: Wed, 7 Aug 2024 12:46:59 -0300 Subject: [PATCH 2/4] =?UTF-8?q?primeira=20tradu=C3=A7=C3=A3o?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/pt/docs/concepts/signals/_index.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/content/pt/docs/concepts/signals/_index.md b/content/pt/docs/concepts/signals/_index.md index d5a38b4c874e..6b69427ce7f6 100644 --- a/content/pt/docs/concepts/signals/_index.md +++ b/content/pt/docs/concepts/signals/_index.md @@ -12,19 +12,14 @@ O objetivo do OpenTelemetry é colletar, processar e exportar **[signals][]**. Sinais são saídas de sistemas que descrevem atividades fundamentais do sistema operacional e aplicações em execução na plataforma. Um sinal pode ser alguma coisa que você quer avaliar em algum ponto específico do tempo, -como temperatura, memória utilizada, ou um evento que passa por um componente -de -something you want to measure at a specific point in time, like temperature or -memory usage, or an event that goes through the components of your distributed -system that you'd like to trace. You can group different signals together to -observe the inner workings of the same piece of technology under different -angles. +como por exemplo, memória utilizada, ou um evento que passa por um componente +do seu sistema distribuido como um trace. você pode agrupar diferentes sinais +para observar o funcionamento interno da mesma tecnologia sob diferentes ângulos. -OpenTelemetry currently supports [traces](/docs/concepts/signals/traces), +OpenTelemetry atualmente suporta [traces](/docs/concepts/signals/traces), [metrics](/docs/concepts/signals/metrics), [logs](/docs/concepts/signals/logs) -and [baggage](/docs/concepts/signals/baggage). _Events_ are a specific type of -log, and +e [baggage](/docs/concepts/signals/baggage). _Events_ são um tipo específico de logs e [_profiles_ are being worked on](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md) -by the Profiling Working Group. +pelo Grupo de Trabalho de Profiling. [signals]: /docs/specs/otel/glossary/#signals From a445eeefc5701b0f75a463b13c6c826bfdd2ae7b Mon Sep 17 00:00:00 2001 From: leandrocarpenter Date: Sun, 11 Aug 2024 12:31:56 -0300 Subject: [PATCH 3/4] =?UTF-8?q?Ajuste=20com=20corre=C3=A7=C3=B5es=20sugeri?= =?UTF-8?q?das=20nos=20coment=C3=A1rios.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/pt/docs/concepts/signals/_index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/pt/docs/concepts/signals/_index.md b/content/pt/docs/concepts/signals/_index.md index 6b69427ce7f6..50422f75a1c8 100644 --- a/content/pt/docs/concepts/signals/_index.md +++ b/content/pt/docs/concepts/signals/_index.md @@ -1,6 +1,6 @@ --- title: Sinais -description: Aprenda sobre a categorias de telemetria suportadas pelo OpenTelemetry. +description: Aprenda sobre as categorias de telemetria suportadas pelo OpenTelemetry. aliases: - /docs/concepts/data-sources - /docs/concepts/otel-concepts @@ -8,18 +8,18 @@ weight: 11 default_lang_commit: 08e13eb62f2869300301670675969be705db59ae --- -O objetivo do OpenTelemetry é colletar, processar e exportar **[signals][]**. +O objetivo do OpenTelemetry é coletar, processar e exportar **[sinais][]**. Sinais são saídas de sistemas que descrevem atividades fundamentais do sistema operacional e aplicações em execução na plataforma. Um sinal pode ser alguma coisa que você quer avaliar em algum ponto específico do tempo, -como por exemplo, memória utilizada, ou um evento que passa por um componente -do seu sistema distribuido como um trace. você pode agrupar diferentes sinais +por exemplo, memória utilizada, ou um evento que passa por um componente +do seu sistema distribuido como um rastro. você pode agrupar diferentes sinais para observar o funcionamento interno da mesma tecnologia sob diferentes ângulos. -OpenTelemetry atualmente suporta [traces](/docs/concepts/signals/traces), -[metrics](/docs/concepts/signals/metrics), [logs](/docs/concepts/signals/logs) +OpenTelemetry atualmente suporta [rastros](/docs/concepts/signals/traces), +[métricas](/docs/concepts/signals/metrics), [logs](/docs/concepts/signals/logs) e [baggage](/docs/concepts/signals/baggage). _Events_ são um tipo específico de logs e -[_profiles_ are being worked on](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md) +[_profiles_ estão em processo de construção](https://github.com/open-telemetry/oteps/blob/main/text/profiles/0212-profiling-vision.md) pelo Grupo de Trabalho de Profiling. -[signals]: /docs/specs/otel/glossary/#signals +[sinais]: /docs/specs/otel/glossary/#signals From 5560e450103f6cf7ea7fb4d793f1f4d771a11e82 Mon Sep 17 00:00:00 2001 From: leandrocarpenter Date: Mon, 12 Aug 2024 10:35:49 -0300 Subject: [PATCH 4/4] =?UTF-8?q?Atualiza=C3=A7=C3=A3o=20de=20tradu=C3=A7?= =?UTF-8?q?=C3=A3o.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/pt/docs/concepts/signals/_baggage.md | 80 ++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 content/pt/docs/concepts/signals/_baggage.md diff --git a/content/pt/docs/concepts/signals/_baggage.md b/content/pt/docs/concepts/signals/_baggage.md new file mode 100644 index 000000000000..86f254ae873e --- /dev/null +++ b/content/pt/docs/concepts/signals/_baggage.md @@ -0,0 +1,80 @@ +--- +title: Bagagem +weight: 4 +description: Informações contextuais que são passadas entre sinais +--- +No OpenTelemetry, bagagem é uma informação adicional associada ao contexto. +Bagagem é uma loja de chave-valor, o que significa que permite que você context. +[propague](/docs/concepts/context-propagation/#propagation) qualquer dado que você +goste ao lado[contexto](/docs/concepts/context-propagation/#context). +Bagagem significa que você pode passar dados entre serviços e processos, +tornando-os disponíveis para adicionar[traços](/docs/concepts/signals/traces/), +[metricas](/docs/concepts/signals/metrics/), or +[logs](/docs/concepts/signals/logs/) nesses serviços. + +## Example + +Bagagem é frequentemente usada no rastreamento para propagar dados adicionais +entre serviços. + +Por exemplo, imagine que você tem um `clientId` no início de uma solicitação, +mas, você gostaria que esse ID estivesse disponível em todos os trechos em um +rastreamento, algumas métricas em outro serviço, e alguns logs ao longo do caminho. +Porque os rastros podem ter vários trechos em multiplos serviços, você precisa de +algumas maneiras para propagar esses dados sem copiar o `clientId` em muitos lugares +na sua base de código. + +Ao usar. +[Contexto Propagação](/docs/concepts/signals/traces/#context-propagation) para +passar bagagem através destes serviços, o `clientId` está disponível para adicionar +a qualquer trecho, métricas ou logs. Além disso, as instrumentações propagam +automaticamente a bagagem para você. + +![OTel Bagagem](/img/otel-baggage.svg) + +## Para que deve ser usada a bagagem Otel? + + +Baggage is best used to include information typically available only at the +start of a request further downstream. This can include things like Account +Identification, User IDs, Product IDs, and origin IPs, for example. + +Propagating this information using baggage allows for deeper analysis of +telemetry in a backend. For example, if you include information like a User ID +on a span that tracks a database call, you can much more easily answer questions +like "which users are experiencing the slowest database calls?" You can also log +information about a downstream operation and include that same User ID in the +log data. + +![OTel Baggage](/img/otel-baggage-2.svg) + +## Baggage security considerations + +Sensitive Baggage items can be shared with unintended resources, like +third-party APIs. This is because automatic instrumentation includes Baggage in +most of your service’s network requests. Specifically, Baggage and other parts +of trace context are sent in HTTP headers, making it visible to anyone +inspecting your network traffic. If traffic is restricted within your network, +then this risk may not apply, but keep in mind that downstream services could +propagate Baggage outside your network. + +Also, there are no built-in integrity checks to ensure that Baggage items are +yours, so exercise caution when reading them. + +## Baggage is not the same as attributes + +An important thing to note about baggage is that it is a separate key-value +store and is unassociated with attributes on spans, metrics, or logs without +explicitly adding them. + +To add baggage entries to attributes, you need to explicitly read the data from +baggage and add it as attributes to your spans, metrics, or logs. + +Because a common use cases for Baggage is to add data to +[Span Attributes](/docs/concepts/signals/traces/#attributes) across a whole +trace, several languages have Baggage Span Processors that add data from baggage +as attributes on span creation. + +> For more information, see the [baggage specification][]. + +[baggage specification]: /docs/specs/otel/overview/#baggage-signal