diff --git a/docs/general/implementation.md b/docs/general/implementation.md index 173fe8f..30107f1 100644 --- a/docs/general/implementation.md +++ b/docs/general/implementation.md @@ -182,21 +182,27 @@ 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-new-span-per-rest-call" %} 클라이언트 라이브러리에서 일으키는 각 REST 호출에 대해 새 스팬 (메서드별 스팬의 자식 스팬이어야 함)을 생성하세요. 이는 일반적으로 HTTP 파이프라인에서 수행됩니다. +{% 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" %} 네임스페이스 또는 비동기 접미사 없이 메서드별 스팬의 이름으로 ` `를 사용해주세요. 대소문자(casing) 또는 구분자에 대한 언어별 규칙을 따르세요. -클라이언트 라이브러리가 수행하는 각 REST 호출에 대해 새 범위(메소드별 범위의 자식이어야 함)를 생성합니다. 이 작업은 일반적으로 HTTP 파이프라인을 사용하여 수행됩니다. +{% include requirement/MUST id="general-tracing-new-span-per-method-duration" %} 요청을 전송하거나 실패할 수 있는 시간 소요가 큰 코드를 호출하기 전에 메서드별 스팬을 시작하세요. 모든 네트워크, IO 또는 기타 불안정하고 시간 소모가 많은 작업이 완료된 후에만 스팬을 종료하세요. -Some of these requirements will be handled by the HTTP pipeline. However, as a client library writer, you must handle the incoming context appropriately. +{% include requirement/MUST id="general-tracing-new-span-per-method-failure" %} 메서드가 예외를 던진 경우, 스팬에 예외를 기록하세요. 예외가 서비스 메서드 내에서 처리되는 경우에는 예외를 기록하지 마세요. + +{% include requirement/MUST id="general-tracing-new-span-per-rest-call" %} 클라이언트 라이브러리에서 일으키는 각 REST 호출에 대해 새 스팬 (메서드별 스팬의 자식 스팬이어야 함)을 생성하세요. 이는 일반적으로 HTTP 파이프라인에서 수행됩니다. 이러한 요구사항들 중 일부는 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 \ No newline at end of file diff --git a/docs/tracing/distributed-tracing-conventions.md b/docs/tracing/distributed-tracing-conventions.md new file mode 100644 index 0000000..c2f85cc --- /dev/null +++ b/docs/tracing/distributed-tracing-conventions.md @@ -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. \ No newline at end of file diff --git a/docs/tracing/distributed-tracing-conventions.yml b/docs/tracing/distributed-tracing-conventions.yml new file mode 100644 index 0000000..88feb5a --- /dev/null +++ b/docs/tracing/distributed-tracing-conventions.yml @@ -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 `` 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 ` 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 ` 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 ` 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 ` process`. E.g. `orders process`. + + # db + # is being moved here: https://github.com/open-telemetry/opentelemetry-specification/pull/3097