Merge pull request #176 from neoseurae12/updated/distributed_tracing
Update the docs: 'Distributed tracing'
This commit is contained in:
Ian Choi
GitHub
Коммит
6e09e62ee3
|
|
@ -182,22 +182,28 @@ HTTP 파이프라인은 여러 정책에 의해 감싸지는 HTTP 전송으로
|
|||
|
||||
## 분산 추적
|
||||
|
||||
분산 추적 메커니즘은 소비자가 프론트엔드에서 백엔드까지 코드를 추적할 수 있도록 합니다. 분산 추적 라이브러리는 고유한 작업 단위인 스팬(span)을 생성합니다. 각 스팬은 부모-자식 관계에 있습니다. 코드의 계층 구조가 깊어질수록 더 많은 스팬이 생성됩니다. 이후에 이러한 스팬은 필요에 따라 적절한 수신기로 내보내질 수 있습니다. 스팬을 추적하기 위해, _분산 추적 컨텍스트_ (이하 컨텍스트)가 각각의 연속된 레이어에 전달됩니다. 이 항목에 대한 자세한 내용은, 추적에 대한 [OpenTelemetry] 항목을 참조하세요.
|
||||
분산 추적 메커니즘은 소비자가 프론트엔드에서 백엔드까지 코드를 추적할 수 있도록 합니다. 분산 추적 라이브러리는 고유한 작업 단위인 스팬(span)을 생성합니다. 각 스팬은 부모-자식 관계에 있습니다. 코드의 계층 구조가 깊어질수록 더 많은 스팬이 생성됩니다. 이후에 이러한 스팬은 필요에 따라 적절한 수신기로 내보내질 수 있습니다. 스팬을 추적하기 위해, _분산 추적 컨텍스트_ (이하 컨텍스트)가 각각의 연속된 레이어에 전달됩니다. 이 항목에 대한 자세한 내용은, 추적에 대한 [OpenTelemetry] 항목을 참조하세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-opentelemetry" %} 분산 추적을 위해 [OpenTelemetry]를 지원하세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-accept-context" %} 부모 스팬을 설정하기 위해 호출 코드로부터 컨텍스트를 받으세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-pass-context" %} [Azure Monitor]를 지원하기 위해 적절한 헤더 (`traceparent`, `tracestate` 등)를 통해 백엔드 서비스에 컨텍스트를 전달하세요. 이는 일반적으로 HTTP 파이프라인에서 수행됩니다.
|
||||
{% include requirement/MUST id="general-tracing-pass-context" %} [Azure Monitor]를 지원하기 위해 적절한 헤더([W3C 추적-컨텍스트](https://www.w3.org/TR/trace-context/) 표준에 따른 `traceparent`와 `tracestate`)를 통해 백엔드 서비스에 컨텍스트를 전달하세요. 이는 일반적으로 HTTP 파이프라인에서 수행됩니다.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method" %} 사용자 코드가 호출한 각 메서드에 대해 새 스팬을 생성하세요. 새 스팬은 전달된 컨텍스트의 자식 스팬이어야 합니다. 전달된 컨텍스트가 없었다면, 새로운 루트 스팬이 만들어져야 합니다.
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method" %} 사용자 코드가 호출하는 클라이언트 메서드에 대해 오직 하나의 스팬만을 생성하세요. 새 스팬은 전달된 컨텍스트의 자식 스팬이어야 합니다. 만약 전달된 컨텍스트가 없었다면, 새로운 루트 스팬이 만들어져야 합니다.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-suppress-client-spans-for-inner-methods" %} 클라이언트 메서드가 새 스팬을 생성하고 동일하거나 다른 Azure SDK의 다른 공개(public) 클라이언트 메서드를 내부적으로 호출하는 경우, 내부 클라이언트 메서드에 대해 생성된 스팬은 반드시 억제되어야 하며, 해당 속성 및 이벤트는 무시되어야 합니다. REST 호출을 위해 만들어진 중첩된 스팬은 외부 클라이언트 호출 스팬의 자식이어야 합니다. 억제(Suppression)는 일반적으로 Azure Core에 의해 수행됩니다.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method-conventions" %} [Tracing Conventions]에 따라 스팬 속성을 채우세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method-naming" %} 네임스페이스 또는 비동기 접미사 없이 메서드별 스팬의 이름으로 `<client> <method>`를 사용해주세요. 대소문자(casing) 또는 구분자에 대한 언어별 규칙을 따르세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method-duration" %} 요청을 전송하거나 실패할 수 있는 시간 소요가 큰 코드를 호출하기 전에 메서드별 스팬을 시작하세요. 모든 네트워크, IO 또는 기타 불안정하고 시간 소모가 많은 작업이 완료된 후에만 스팬을 종료하세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-method-failure" %} 메서드가 예외를 던진 경우, 스팬에 예외를 기록하세요. 예외가 서비스 메서드 내에서 처리되는 경우에는 예외를 기록하지 마세요.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-new-span-per-rest-call" %} 클라이언트 라이브러리에서 일으키는 각 REST 호출에 대해 새 스팬 (메서드별 스팬의 자식 스팬이어야 함)을 생성하세요. 이는 일반적으로 HTTP 파이프라인에서 수행됩니다.
|
||||
|
||||
클라이언트 라이브러리가 수행하는 각 REST 호출에 대해 새 범위(메소드별 범위의 자식이어야 함)를 생성합니다. 이 작업은 일반적으로 HTTP 파이프라인을 사용하여 수행됩니다.
|
||||
|
||||
Some of these requirements will be handled by the HTTP pipeline. However, as a client library writer, you must handle the incoming context appropriately.
|
||||
|
||||
이러한 요구사항들 중 일부는 HTTP 파이프라인에서 처리될 것입니다. 그러나, 클라이언트 라이브러리 작성자로서, 당신은 들어오는 컨텍스트를 적절하게 처리해야 합니다.
|
||||
|
||||
|
||||
|
|
@ -291,5 +297,6 @@ Some of these requirements will be handled by the HTTP pipeline. However, as a
|
|||
[Azure Monitor]: https://azure.microsoft.com/services/monitor/
|
||||
[1]: https://www.youtube.com/watch?v=PAAkCSZUG1c&t=9m28s
|
||||
[2]: https://martinfowler.com/bliki/TestCoverage.html
|
||||
[Tracing Conventions]: {{ site.baseurl }}{% link docs/tracing/distributed-tracing-conventions.md %}
|
||||
|
||||
[General Guidelines: Implementation]: https://azure.github.io/azure-sdk/general_implementation.html
|
||||
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
title: "Distributed Tracing Conventions"
|
||||
permalink: distributed_tracing_conventions.html
|
||||
keywords: opentelemetry conventions
|
||||
folder: general
|
||||
sidebar: general_sidebar
|
||||
---
|
||||
|
||||
Conventions are the contract between Azure SDK and tracing providers such as Azure Monitor, Jaeger and others. They describe and standardize attributes, events and relationships for common span types: HTTP, DB, messaging and others. Observability vendors use conventions to build visualizations and may be very sensitive to them. Custom Azure SDK conventions are described in [tracing-conventions.yml](./distributed-tracing-conventions.yml) and include:
|
||||
|
||||
- Custom Azure SDK attributes
|
||||
- Azure SDK HTTP conventions compatible with OpenTelemetry
|
||||
- Custom messaging and DB conventions. They don't follow OpenTelemetry convention and used until OpenTelemetry conventions evolve and stabilize
|
||||
|
||||
When writing instrumentation in Azure SDK or Core:
|
||||
|
||||
{% include requirement/MUST id="general-tracing-convention-use-otel" %} use [OpenTelemetry conventions](https://opentelemetry.io/docs/specs/otel/trace/semantic_conventions/) whenever possible.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-convention-describe-attributes" %} update [distributed-tracing-conventions.yml](./distributed-tracing-conventions.yml) when adding new attributed.
|
||||
|
||||
{% include requirement/MUST id="general-tracing-convention-set-schema-version" %} set OpenTelemetry [Schema URL](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/README.md?plain=1) when [creating OpenTelemetry tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer).
|
||||
|
||||
{% include requirement/SHOULD id="general-tracing-convention-set-library" %} set Azure Client Library name and version [Schema URL](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer) when [creating OpenTelemetry tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer).
|
||||
|
||||
|
||||
{% include requirement/SHOULD id="general-tracing-convention-new-otel" %} contribute new conventions (or patch existing ones) to OpenTelemetry when there is no suitable one or some scenarios are missing.
|
||||
|
||||
{% include requirement/MAY id="general-tracing-convention-add-attributes" %} extend list of attributes on top of OpenTelemetry contentions with Azure-specific ones.
|
||||
|
||||
{% include requirement/MUSTNOT id="general-tracing-convention-new-custom" %} add new custom Azure SDK conventions.
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
# This document describes Azure SDK semantic conventions for tracing in [OpenTelemetry format](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/syntax.md).
|
||||
# DO NOT add new conventions - use [OpenTelemetry conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/semantic_conventions), but it's ok to extend existing ones.
|
||||
# Version: 0.1.0
|
||||
|
||||
groups:
|
||||
# common
|
||||
- id: azure-sdk
|
||||
brief: 'Describes Azure SDK spans.'
|
||||
type: attribute_group
|
||||
attributes:
|
||||
- id: az.namespace
|
||||
requirement_level: required
|
||||
type: string
|
||||
brief: '[Namespace](https://docs.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) of Azure service request is made against.'
|
||||
examples: ['Microsoft.Storage', 'Microsoft.KeyVault', 'Microsoft.ServiceBus']
|
||||
- id: az.schema_url
|
||||
requirement_level:
|
||||
conditionally_required: if and only if OpenTelemetry in given language does not provide standard way to set schema_url (i.e. .NET) # https://opentelemetry.io/docs/reference/specification/schemas/#schema-url
|
||||
type: string
|
||||
brief: 'OpenTelemetry Schema URL including schema version. Only 1.17.0 is supported.'
|
||||
examples: ['https://opentelemetry.io/schemas/1.17.0']
|
||||
|
||||
# public API
|
||||
- id: azure-sdk.api
|
||||
type: span
|
||||
span_kind: internal
|
||||
extends: azure-sdk
|
||||
brief: 'Describes Azure SDK API calls spans.'
|
||||
note: >
|
||||
Represents public surface API calls that wrap an Azure service call.
|
||||
|
||||
Span name SHOULD match `<short-class-name.method>` pattern. Class and method name SHOULD match API user called close enough for users
|
||||
to understand which method span matches to.
|
||||
For example, `BlobClient.Download` could be used for different overloads of download method, it can also coexist with `BlobClient.DownloadToFile` or
|
||||
`BlobClient.DownloadAsync`.
|
||||
|
||||
# network calls
|
||||
- id: azure-sdk.network
|
||||
type: attribute_group
|
||||
extends: azure-sdk
|
||||
brief: 'Describes Azure SDK client spans.'
|
||||
note: 'Represents calls that include network attributes'
|
||||
attributes:
|
||||
- ref: net.peer.name
|
||||
requirement_level: required
|
||||
sampling_relevant: true
|
||||
type: string
|
||||
brief: 'Fully qualified Azure service endpoint (host name component).'
|
||||
examples: 'http://my-account.servicebus.windows.net/'
|
||||
- ref: net.peer.port
|
||||
requirement_level:
|
||||
conditionally_required: if not 80 or 443.
|
||||
sampling_relevant: true
|
||||
brief: Port of Azure service endpoint.'
|
||||
type: int
|
||||
examples: [8080]
|
||||
constraints:
|
||||
- include: network #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/general.yaml
|
||||
|
||||
# http
|
||||
- id: azure-sdk.http
|
||||
type: span
|
||||
span_kind: client
|
||||
extends: azure-sdk.network
|
||||
brief: 'Describes HTTP client spans created per HTTP request (try).'
|
||||
note: >
|
||||
This conventions follows [OpenTelemetry HTTP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md)
|
||||
but omits all optional attributes, providing only `http.url` to describe destination. It adds request-id attributes supported by Azure services.
|
||||
|
||||
Span name MUST NOT include dynamic parts and SHOULD follow `HTTP <method>` pattern. E.g. `HTTP GET`.
|
||||
attributes:
|
||||
- ref: http.method
|
||||
requirement_level: required
|
||||
sampling_relevant: true
|
||||
- ref: http.url
|
||||
requirement_level: required
|
||||
sampling_relevant: true
|
||||
- ref: http.status_code
|
||||
requirement_level: required
|
||||
- ref: http.user_agent
|
||||
type: string
|
||||
brief: 'Value of the HTTP User-Agent or x-ms-user-agent header'
|
||||
- id: az.client_request_id
|
||||
type: string
|
||||
requirement_level:
|
||||
conditionally_required: only if present
|
||||
brief: 'Value of the [x-ms-client-request-id] header (or other request-id header, depending on the service) sent by the client.'
|
||||
examples: ['eb178587-c05a-418c-a695-ae9466c5303c']
|
||||
- id: az.service_request_id
|
||||
type: string
|
||||
requirement_level:
|
||||
conditionally_required: if and only if one was received
|
||||
brief: 'Value of the [x-ms-request-id] header (or other request-id header, depending on the service) sent by the server in response.'
|
||||
examples: ['3f828ae5-ecb9-40ab-88d9-db0420af30c6']
|
||||
constraints:
|
||||
- include: http.client #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/http.yaml
|
||||
|
||||
# messaging
|
||||
- id: azure-sdk.messaging
|
||||
type: span
|
||||
brief: 'Describes Azure messaging SDKs spans.'
|
||||
extends: azure-sdk.network
|
||||
attributes:
|
||||
- ref: messaging.system
|
||||
requirement_level: required
|
||||
sampling_relevant: true
|
||||
examples: ['eventhubs', 'servicebus']
|
||||
- ref: messaging.destination.name
|
||||
requirement_level: required
|
||||
sampling_relevant: true
|
||||
brief: 'Name of the messaging entity within namespace: e.g EventHubs name, ServiceBus queue or topic name. Must not include partition or subscription'
|
||||
examples: ['myqueue', 'myhub']
|
||||
- ref: messaging.operation
|
||||
- ref: messaging.batch.message_count
|
||||
constraints:
|
||||
- include: messaging #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/messaging.yaml
|
||||
|
||||
- id: azure-sdk.messaging.producer
|
||||
span_kind: producer
|
||||
extends: azure-sdk
|
||||
brief: 'Describes producer span created per message.'
|
||||
note: Span name SHOULD match `<queue/topic_name> message`. E.g. `orders message`.
|
||||
|
||||
- id: azure-sdk.messaging.send
|
||||
span_kind: client
|
||||
extends: azure-sdk.messaging
|
||||
brief: 'Describes Azure messaging SDKs producer client spans.'
|
||||
note: >
|
||||
Contains links to all messages contexts being sent.
|
||||
Span name SHOULD match `<queue/topic_name> publish`. E.g. `orders publish`.
|
||||
|
||||
|
||||
- id: azure-sdk.messaging.process
|
||||
span_kind: consumer
|
||||
extends: azure-sdk.messaging
|
||||
brief: 'Describes consumption span.'
|
||||
note: >
|
||||
Contains links to all messages contexts being consumed. Each link has attribute `enqueuedTime` (with `long` type)
|
||||
attribute with unix epoch time with milliseconds precision representing when message was enqueued.
|
||||
Span name SHOULD match `<queue/topic_name> process`. E.g. `orders process`.
|
||||
|
||||
# db
|
||||
# is being moved here: https://github.com/open-telemetry/opentelemetry-specification/pull/3097
|
||||
Загрузка…
Ссылка в новой задаче