├── .github └── CODEOWNERS ├── .gitmodules ├── LICENSE ├── README.md └── specification ├── Makefile ├── README.md ├── internal └── img │ ├── api-lifecycle.png │ ├── architecture.png │ ├── dynamic-config-service.png │ ├── library-design.png │ ├── library-full.png │ ├── library-minimal.png │ └── long-term-support.png ├── semantic_conventions ├── README.md ├── resource │ ├── cloud.yaml │ ├── cloud_provider │ │ └── aws │ │ │ ├── ecs.yaml │ │ │ ├── eks.yaml │ │ │ └── logs.yaml │ ├── container.yaml │ ├── deployment_environment.yaml │ ├── faas.yaml │ ├── host.yaml │ ├── k8s.yaml │ ├── os.yaml │ ├── process.yaml │ ├── service.yaml │ ├── telemetry.yaml │ └── webengine.yaml ├── syntax.md ├── trace │ ├── database.yaml │ ├── exception.yaml │ ├── faas.yaml │ ├── general.yaml │ ├── http.yaml │ ├── instrumentation │ │ └── aws-sdk.yml │ ├── messaging.yaml │ └── rpc.yaml └── version.properties ├── spec-compliance-matrix.md └── specification ├── baggage └── api.md ├── common ├── attribute-and-label-naming.md └── common.md ├── compatibility ├── opencensus.md ├── openmetrics.md └── opentracing.md ├── context ├── api-propagators.md └── context.md ├── document-status.md ├── error-handling.md ├── glossary.md ├── library-guidelines.md ├── library-layout.md ├── logs ├── data-model.md ├── img │ ├── app-to-file-logs-fb.png │ ├── app-to-file-logs-otelcol.png │ ├── app-to-otelcol.png │ ├── application-api-sdk.png │ ├── separate-collection.png │ └── unified-collection.png └── overview.md ├── metrics ├── README.md ├── api.md ├── datamodel.md ├── img │ ├── accumulator-detail.png │ ├── metrics-sdk.png │ ├── model-cumulative-sum.png │ ├── model-delta-sum.png │ ├── model-event-layer.png │ ├── model-layers-stream.png │ └── model-layers.png ├── new_api.md └── semantic_conventions │ ├── README.md │ ├── http-metrics.md │ ├── openmetrics-guidelines.md │ ├── process-metrics.md │ ├── rpc.md │ ├── runtime-environment-metrics.md │ └── system-metrics.md ├── overview.md ├── performance-benchmark.md ├── performance.md ├── protocol ├── README.md ├── design-goals.md ├── exporter.md ├── img │ ├── otlp-client-server.png │ ├── otlp-concurrent.png │ ├── otlp-multi-destination.png │ ├── otlp-request-response.png │ └── otlp-sequential.png ├── otlp.md └── requirements.md ├── resource ├── sdk.md └── semantic_conventions │ ├── README.md │ ├── cloud.md │ ├── cloud_provider │ └── aws │ │ ├── README.md │ │ ├── ecs.md │ │ ├── eks.md │ │ └── logs.md │ ├── container.md │ ├── deployment_environment.md │ ├── faas.md │ ├── host.md │ ├── k8s.md │ ├── os.md │ ├── process.md │ └── webengine.md ├── sdk-configuration.md ├── sdk-environment-variables.md ├── trace ├── api.md ├── sdk.md ├── sdk_exporters │ ├── jaeger.md │ ├── non-otlp.md │ └── zipkin.md └── semantic_conventions │ ├── README.md │ ├── database.md │ ├── exceptions.md │ ├── faas.md │ ├── http.md │ ├── instrumentation │ ├── aws-lambda.md │ └── aws-sdk.md │ ├── messaging.md │ ├── rpc.md │ └── span-general.md ├── vendors.md └── versioning-and-stability.md /.github/CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @ymotongpoo @katzchang @shirou -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "original/specification"] 2 | path = original/specification 3 | url = git@github.com:open-telemetry/opentelemetry-specification.git 4 | [submodule "original/community"] 5 | path = original/community 6 | url = git@github.com:open-telemetry/community.git 7 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OpenTelemetry ドキュメント日本語化プロジェクト 2 | 3 | > [!IMPORTANT] 4 | > このレポジトリはアーカイブされたので、新規のIssueやPull Requestは受け付けていません。 5 | > OpenTelemetryのドキュメントとウェブサイトのローカライズは[ウェブサイトのレポジトリ](https://github.com/open-telemetry/opentelemetry.io)で行っています。 6 | > 7 | > This repository is archived and will not receive any updates or accept issues or pull requests 8 | > 9 | > Localizations for the OpenTelemetry documentation and website are now part of the [website repository](https://github.com/open-telemetry/opentelemetry.io) 10 | 11 | OpenTelemetry documents Japanese translation poject 12 | 13 | ## 翻訳対象ドキュメント (Target repositories) 14 | 15 | * [community](https://github.com/open-telemetry/community) 16 | * 67d8f20a8b0cb49e3fd9033545c3f9e5865de7cf (2021-02-11バージョン) 17 | * [specification](https://github.com/open-telemetry/opentelemetry-specification) 18 | * v1.3.0 19 | 20 | ## 翻訳に取り掛かる前に 21 | 22 | ### 訳語について 23 | 24 | 翻訳プロジェクトへようこそ。この翻訳プロジェクトでは、全体的に翻訳に統一感を出すための工夫をしています。 25 | 26 | * 訳語一覧: [wikiのDictionary](https://github.com/open-telemetry/docs-ja/wiki/Dictionary) で英語と日本語の対訳の一覧を作成しているので、翻訳時にこちらに揃えてください。 27 | * 助動詞について: 原文はBCP 14に準ずると[明記しているので](https://github.com/open-telemetry/opentelemetry-specification#notation-conventions-and-compliance)、日本語訳もそれに従います。 28 | * 参照: https://www.nic.ad.jp/ja/tech/ipa/RFC2119JA.html 29 | 30 | **TODO: textlintなどの方法である程度自動化する** 31 | 32 | ### 機械翻訳の使用について 33 | 34 | 機械翻訳を利用して翻訳作業を行うことは技術の正しい利用方法だと思います。 35 | しかしながら、サービスによっては次のような問題があるため注意が必要です。 36 | 37 | * 翻訳結果の著作権（例: DeepL無料版、Google翻訳など） 38 | * 翻訳結果自体の品質 39 | 40 | したがって、機械翻訳を利用する場合には、上記の懸念が明確にないと確認できる状況以外では、機械翻訳による翻訳結果をそのままレポジトリにpushすることは避けてください。（各種サービスがCNCFのCLAにサインしたわけでもないため） 41 | 42 | ## コントリビューションワークフロー 43 | 44 | 1. Issueより対象のドキュメントに対し作業に取り掛かる旨コメントしてください。 45 | 2. 作業ドキュメントは原文の英語ドキュメントをコピーし、翻訳を進めるにあたりそれをコメントアウトする形で勧めてください。([参考](https://raw.githubusercontent.com/open-telemetry/docs-ja/main/specification/specification/library-guidelines.md)) 46 | 4. 作業中は `WIP` をつけたブランチを作成しPRを早めに出してください。 47 | 5. Reviewerがレビューを行ってapproveされるまで修正をお願いします。 48 | 6. ApproveされたものはCODEOWNERSの誰かがsquash mergeします。 49 | 50 | もし翻訳等で質問がある場合はIssueでコメントしてください。 51 | 52 | ## チャット 53 | 54 | 翻訳プロジェクトのチャットはこちらのdiscordの `#otel-docs-ja` チャンネルで行っています。 55 | 56 | https://discord.gg/vYKuzFK 57 | 58 | ## 翻訳者ミーティング 59 | 60 | よりオープンなプロジェクトにするために、オープンな定期ミーティングを計画しています。 61 | -------------------------------------------------------------------------------- /specification/Makefile: -------------------------------------------------------------------------------- 1 | # All documents to be used in spell check. 2 | ALL_DOCS := $(shell find . -name '*.md' -not -path './.github/*' -type f | grep -v ^./node_modules | sort) 3 | PWD := $(shell pwd) 4 | 5 | TOOLS_DIR := ./internal/tools 6 | MISSPELL_BINARY=bin/misspell 7 | MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) 8 | MARKDOWN_LINK_CHECK=markdown-link-check 9 | MARKDOWN_LINT=markdownlint 10 | # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates 11 | SEMCONVGEN_VERSION=0.3.1 12 | 13 | .PHONY: install-misspell 14 | install-misspell: 15 | # TODO: Check for existence before installing 16 | cd $(TOOLS_DIR) && go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell 17 | 18 | .PHONY: misspell 19 | misspell: 20 | $(MISSPELL) -error $(ALL_DOCS) 21 | 22 | .PHONY: misspell-correction 23 | misspell-correction: 24 | $(MISSPELL) -w $(ALL_DOCS) 25 | 26 | .PHONY: install-markdown-link-check 27 | install-markdown-link-check: 28 | # TODO: Check for existence before installing 29 | npm install -g $(MARKDOWN_LINK_CHECK) 30 | 31 | .PHONY: markdown-link-check 32 | markdown-link-check: 33 | @for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done 34 | 35 | .PHONY: install-markdownlint 36 | install-markdownlint: 37 | # TODO: Check for existence before installing 38 | npm install -g markdownlint-cli 39 | 40 | .PHONY: markdownlint 41 | markdownlint: 42 | @for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1; done 43 | 44 | # Generate markdown tables from YAML definitions 45 | .PHONY: table-generation 46 | table-generation: 47 | docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \ 48 | otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec 49 | 50 | # Check if current markdown tables differ from the ones that would be generated from YAML definitions 51 | .PHONY: table-check 52 | table-check: 53 | docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \ 54 | otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check 55 | 56 | # Run all checks in order of speed / likely failure. 57 | .PHONY: check 58 | check: misspell markdownlint markdown-link-check 59 | @echo "All checks complete" 60 | 61 | # Attempt to fix issues / regenerate tables. 62 | .PHONY: fix 63 | fix: table-generation misspell-correction 64 | @echo "All autofixes complete" 65 | 66 | # Attempt to install all the tools 67 | .PHONY: install-tools 68 | install-tools: install-misspell install-markdownlint install-markdown-link-check 69 | @echo "All tools installed" 70 | -------------------------------------------------------------------------------- /specification/README.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry 仕様 6 | 7 | [![Checks](https://github.com/open-telemetry/opentelemetry-specification/workflows/Checks/badge.svg?branch=main)](https://github.com/open-telemetry/opentelemetry-specification/actions?query=workflow%3A%22Checks%22+branch%3Amain) 8 | ![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/open-telemetry/specification.svg) 9 | 10 | ![OpenTelemetry Logo](https://opentelemetry.io/img/logos/opentelemetry-horizontal-color.png) 11 | 12 | 15 | 16 | _OpenTelemetryが何であるかについて興味がありますか？私たちの[ウェブサイト](https://opentelemetry.io)で説明をチェックしてみてください！_。 17 | 18 | 21 | 22 | OpenTelemetry仕様は、すべてのOpenTelemetry実装に対する言語横断的な要求事項と期待事項を記述したものです。仕様に対する実質的な変更は、[OpenTelemetry Enhancement Proposal](https://github.com/open-telemetry/oteps)プロセスを使って提案しなければなりません。明瞭化、表現の変更、スペルや文法の修正などの小さな変更は、プルリクエストを通じて直接行うことができます。 23 | 24 | 32 | 33 | さらに注意が必要な質問は、通常の仕様会議に持ち込むことができます。EUとアメリカのタイムゾーンに合わせたミーティングは、毎週火曜日の午前8時(太平洋時間)に行われます。ミーティングノートは[google doc](https://docs.google.com/document/d/1-bCYkN-DWJq4jw1ybaDZYYmx-WAe6HnwfWbkm8d57v8/edit?usp=sharing)にあります。APACのタイムゾーンフレンドリーミーティングは、毎週火曜日の午後4時(太平洋時間)に開催されます。[OpenTelemetry calendar](https://github.com/open-telemetry/community#calendar)をご覧ください。 34 | 35 | 41 | 42 | 技術委員会へのエスカレーションは、[e-mail](https://github.com/open-telemetry/community#tc-technical-committee)で行うことができます。技術委員会は定期的に開催され、ノートは[こちら](https://docs.google.com/document/d/17v2RMZlJZkgoPYHZhIFTVdDqQMIAH8kzo8Sl2kP3cbY/edit?usp=sharing)にあります。 43 | 44 | 47 | 48 | ## 目次 49 | 50 | 80 | 81 | - [概要](specification/overview.md) 82 | - [用語集](specification/glossary.md) 83 | - [OpenTelemetryクライアントのバージョニングと安定性](specification/versioning-and-stability.md) 84 | - [ライブラリガイドライン](specification/library-guidelines.md) 85 | - [パッケージ/ライブラリレイアウト](specification/library-layout.md) 86 | - [エラー処理ガイドライン](specification/error-handling.md) 87 | - API仕様 88 | - [Context](specification/context/context.md) 89 | - [Propagators](specification/context/api-propagators.md) 90 | - [Baggage](specification/baggage/api.md) 91 | - [Tracing](specification/trace/api.md) 92 | - [Metrics](specification/metrics/api.md) 93 | - [Metrics](specification/metrics/datamodel.md) 94 | - [Logs](specification/logs/data-model.md) 95 | - SDK仕様 96 | - [Tracing](specification/trace/sdk.md) 97 | - [Resource](specification/resource/sdk.md) 98 | - [Configuration](specification/sdk-configuration.md) 99 | - Data仕様 100 | - [セマンティック規約](specification/overview.md#semantic-conventions) 101 | - [Protocol](specification/protocol/README.md) 102 | - このプロジェクトについて 103 | - [タイムライン](#プロジェクトタイムライン) 104 | - [表記規則とコンプライアンス](#表記規則とコンプライアンス) 105 | - [仕様のバージョニング](#仕様のバージョニング) 106 | - [略語](#略語) 107 | - [貢献](#貢献) 108 | - [ライセンス](#license) 109 | 110 | 113 | 114 | ## プロジェクトタイムライン 115 | 116 | 120 | 121 | 現在のプロジェクトの状況や、注目すべき過去のリリースに関する情報は、[OpenTelemetryプロジェクトのページ](https://opentelemetry.io/project-status/)に掲載されています。 122 | 123 | 127 | 128 | 現在の作業と将来の開発計画に関する情報は、[仕様開発マイルストーン](https://github.com/open-telemetry/opentelemetry-specification/milestones)にあります。 129 | 130 | 133 | 134 | ## 表記規則とコンプライアンス 135 | 136 | 139 | 140 | [仕様書](./specification/overview.md)に記載されているキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、「OPTIONAL」は、[BCP 14](https://tools.ietf.org/html/bcp14) 、[[RFC2119](https://tools.ietf.org/html/rfc2119)]、[[RFC8174](https://tools.ietf.org/html/rfc8174)]に記載されているとおりに解釈されます。これらはすべて大文字で表示されている場合に限り、解釈されます。 141 | 142 | 143 | 147 | 148 | [仕様書](./specification/overview.md)の実装は、[仕様書](./specification/overview.md)で定義されている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」のうち、1つ以上の要件を満たしていない場合、準拠していません。逆に、[仕様書](./specification/overview.md)の実装は、[仕様書](./specification/overview.md)で定義されている「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」のすべての要件を満たす場合、準拠していることになります。 149 | 150 | 153 | 154 | ## 仕様のバージョニング 155 | 156 | 159 | 160 | [仕様書](./specification/overview.md)への変更は、[Semantic Versioning 2.0](https://semver.org/spec/v2.0.0.html)に従ってバージョン管理され、[CHANGELOG.md](CHANGELOG.md)に記述されます。レイアウトの変更はバージョン管理されません。本仕様の特定の実装では、どのバージョンを実装するかを指定する必要があります。 161 | 162 | 165 | 166 | 変更プロセス自体の変更は、現在はバージョン管理されていませんが、将来的には独立してバージョン管理される可能性があります。 167 | 168 | 171 | 172 | ## 略語 173 | 174 | 177 | 178 | OpenTelemetryプロジェクトで使用されている公式の略語は "OTel"です。 179 | 180 | 183 | 184 | 現在は廃止された "OpenTracing"プロジェクトとの混同を避けるために、"OT"の使用は控えてください。 185 | 186 | 189 | 190 | ## 貢献 191 | 192 | 195 | 196 | コントリビューションプロセスの詳細については、[CONTRIBUTING.md](CONTRIBUTING.md)を参照してください。 197 | 198 | 201 | 202 | ## ライセンス 203 | 204 | 207 | 208 | OpenTelemetry 仕様のリポジトリに貢献することで、あなたの貢献が[Apache 2.0 License](https://github.com/open-telemetry/specification/blob/main/LICENSE)の下でライセンスされることに同意することになります。 -------------------------------------------------------------------------------- /specification/internal/img/api-lifecycle.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/api-lifecycle.png -------------------------------------------------------------------------------- /specification/internal/img/architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/architecture.png -------------------------------------------------------------------------------- /specification/internal/img/dynamic-config-service.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/dynamic-config-service.png -------------------------------------------------------------------------------- /specification/internal/img/library-design.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/library-design.png -------------------------------------------------------------------------------- /specification/internal/img/library-full.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/library-full.png -------------------------------------------------------------------------------- /specification/internal/img/library-minimal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/library-minimal.png -------------------------------------------------------------------------------- /specification/internal/img/long-term-support.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/internal/img/long-term-support.png -------------------------------------------------------------------------------- /specification/semantic_conventions/README.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # セマンティック規約のためのYAMLモデル 6 | 7 | 12 | 13 | このディレクトリに含まれるセマンティック規約のYAML記述は、セマンティック関連のコードの自動生成を支援するために、様々なOpenTelemetryの各言語向け実装によって使用されることを意図しています。 14 | 15 | 16 | 19 | 20 | ## セマンティック規約の書き方 21 | 22 | 25 | 26 | YAMLファイルの書き方については、[syntax](./syntax.md)を参考にしてください。 27 | 28 | 31 | 32 | ## 世代 33 | 34 | 38 | 39 | これらのYAMLファイルはmakeターゲットの`table-generation`によって仕様のすべてのセマンティック規約のために、一貫してフォーマットされたMarkdownテーブルを生成するために使われます。このリポジトリの直下からコマンドを使って実行してください。 40 | 41 | 42 | ``` 43 | make table-generation 44 | ``` 45 | 46 | 52 | 53 | 詳細については、OpenTelemetry ビルドツールのリポジトリにある [セマンティック規約ジェネレータ](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions) を参照してください。このビルドツールを使用すると、OpenTelemetry言語プロジェクトで使用するコードを生成することも可能です。 54 | 55 | 58 | 59 | こちらも参考: 60 | 61 | 65 | 66 | * [Markdownテーブル](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#markdown-tables) 67 | * [コード生成](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#code-generator) 68 | 69 | 72 | 73 | ## モデルの説明 74 | 75 | 78 | 79 | フィールドとその期待値は、[syntax.md] (./syntax.md)で示されています。 80 | 81 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/cloud.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: cloud 3 | prefix: cloud 4 | brief: > 5 | クラウド環境 (例: GCP, Azure, AWS) 6 | attributes: 7 | - id: provider 8 | type: 9 | allow_custom_values: true 10 | members: 11 | - id: AWS 12 | value: 'aws' 13 | brief: 'Amazon Web Services' 14 | - id: Azure 15 | value: 'azure' 16 | brief: 'Microsoft Azure' 17 | - id: GCP 18 | value: 'gcp' 19 | brief: 'Google Cloud Platform' 20 | brief: > 21 | クラウドプロバイダの名前 22 | examples: 'gcp' 23 | - id: account.id 24 | type: string 25 | brief: > 26 | リソースが割り当てられているクラウドのアカウントID 27 | examples: ['111111111111', 'opentelemetry'] 28 | - id: region 29 | type: string 30 | brief: > 31 | リソースが動作している地理的な地域。[AWSリージョン](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)、[Azureリージョン](https://azure.microsoft.com/en-us/global-infrastructure/geographies/)、[Google Cloudリージョン](https://cloud.google.com/about/locations)など、利用可能なリージョンについては、プロバイダーのドキュメントを参照してください。 32 | examples: ['us-central1', 'us-east-1'] 33 | - id: availability_zone 34 | type: string 35 | brief: > 36 | クラウドのリージョンは、可用性を高めるために、ゾーンと呼ばれる複数の隔離された場所を持つことが多いです。アベイラビリティゾーンは、リソースが稼働しているゾーンを表します。 37 | note: > 38 | Google Cloudでは、アベイラビリティー・ゾーンを"Zone"と呼んでいます。 39 | examples: ['us-east-1c'] 40 | - id: platform 41 | type: 42 | allow_custom_values: true 43 | members: 44 | - id: aws_ec2 45 | value: 'aws_ec2' 46 | brief: AWS Elastic Compute Cloud 47 | - id: aws_ecs 48 | value: 'aws_ecs' 49 | brief: AWS Elastic Container Service 50 | - id: aws_eks 51 | value: 'aws_eks' 52 | brief: AWS Elastic Kubernetes Service 53 | - id: aws_lambda 54 | value: 'aws_lambda' 55 | brief: AWS Lambda 56 | - id: aws_elastic_beanstalk 57 | value: 'aws_elastic_beanstalk' 58 | brief: AWS Elastic Beanstalk 59 | - id: azure_vm 60 | value: 'azure_vm' 61 | brief: Azure Virtual Machines 62 | - id: azure_container_instances 63 | value: 'azure_container_instances' 64 | brief: Azure Container Instances 65 | - id: azure_aks 66 | value: 'azure_aks' 67 | brief: Azure Kubernetes Service 68 | - id: azure_functions 69 | value: 'azure_functions' 70 | brief: Azure Functions 71 | - id: azure_app_service 72 | value: 'azure_app_service' 73 | brief: Azure App Service 74 | - id: gcp_compute_engine 75 | value: 'gcp_compute_engine' 76 | brief: Google Cloud Compute Engine (GCE) 77 | - id: gcp_cloud_run 78 | value: 'gcp_cloud_run' 79 | brief: Google Cloud Run 80 | - id: gcp_kubernetes_engine 81 | value: 'gcp_kubernetes_engine' 82 | brief: Google Cloud Kubernetes Engine (GKE) 83 | - id: gcp_cloud_functions 84 | value: 'gcp_cloud_functions' 85 | brief: Google Cloud Functions (GCF) 86 | - id: gcp_app_engine 87 | value: 'gcp_app_engine' 88 | brief: Google Cloud App Engine (GAE) 89 | brief: > 90 | 使用中のクラウドプラットフォームのリソース 91 | note: > 92 | サービスのプレフィックスは `cloud.provider` で指定されたものと一致するべきです(SHOULD)。 93 | examples: ['aws_ec2', 'azure_vm', 'gcp_compute_engine'] 94 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/cloud_provider/aws/ecs.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: aws.ecs 3 | prefix: aws.ecs 4 | brief: > 5 | AWS Elastic Container Service(ECS)が利用するResource。 6 | attributes: 7 | - id: container.arn 8 | type: string 9 | brief: > 10 | [ECSコンテナインスタンス](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html)のAmazon Resource Name(ARN)。 11 | examples: ['arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9'] 12 | - id: cluster.arn 13 | type: string 14 | brief: > 15 | [ECSクラスタ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html)のARN。 16 | examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] 17 | - id: launchtype 18 | type: 19 | allow_custom_values: false 20 | members: 21 | - id: ec2 22 | value: "ec2" 23 | - id: fargate 24 | value: "fargate" 25 | brief: > 26 | ECSタスクの[起動タイプ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html)。 27 | examples: ['ec2', 'fargate'] 28 | - id: task.arn 29 | type: string 30 | brief: > 31 | [ECSタスク定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html)のARN。 32 | examples: ['arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b'] 33 | - id: task.family 34 | type: string 35 | brief: > 36 | このタスク定義が属するタスク定義ファミリ。 37 | examples: ['opentelemetry-family'] 38 | - id: task.revision 39 | type: string 40 | brief: > 41 | このタスク定義のリビジョン 42 | examples: ["8", "26"] 43 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/cloud_provider/aws/eks.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: aws.eks 3 | prefix: aws.eks 4 | brief: > 5 | AWS Elastic Kubernetes Service(EKS)が使用するリソース 6 | attributes: 7 | - id: cluster.arn 8 | type: string 9 | brief: > 10 | EKSクラスターのARN 11 | examples: ['arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster'] -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/cloud_provider/aws/logs.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: aws.log 3 | prefix: aws.log 4 | brief: > 5 | Amazon Web Servicesに特化したリソース。 6 | attributes: 7 | - id: group.names 8 | type: string[] 9 | brief: > 10 | アプリケーションが書き込んでいるAWS log groupの名前。 11 | examples: ['/aws/lambda/my-function', 'opentelemetry-service'] 12 | note: > 13 | マルチコンテナアプリケーションのように1つのアプリケーションにサイドカーコンテナがあり、それぞれがそれぞれのロググループに書き込むような場合があるため、複数のロググループをサポートする必要があります。 14 | - id: group.arns 15 | type: string[] 16 | brief: > 17 | AWSロググループのAmazon Resource Name(ARN)。 18 | examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*'] 19 | note: > 20 | [ロググループ ARN 形式のドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format) を参照してください。 21 | - id: stream.names 22 | type: string[] 23 | brief: > 24 | アプリケーションが書き込んでいるAWSログストリームの名前。 25 | examples: ['logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] 26 | - id: stream.arns 27 | type: string[] 28 | brief: > 29 | AWSログストリームのARN。 30 | examples: ['arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b'] 31 | note: > 32 | [ログストリーム ARN 形式のドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format)を参照してください。1つのロググループには複数のログストリームを含むことができるので、これらのARNは必然的にロググループとログストリームの両方を識別する必要があります。 33 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/container.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: container 3 | prefix: container 4 | brief: > 5 | コンテナインスタンス 6 | attributes: 7 | - id: name 8 | type: string 9 | brief: > 10 | コンテナ名 11 | examples: ['opentelemetry-autoconf'] 12 | - id: id 13 | type: string 14 | brief: > 15 | コンテナID。通常はUUIDで、例えば[Dockerコンテナの識別子](https://docs.docker.com/engine/reference/run/#container-identification)]に使用されます。UUIDが略されている場合があります。 16 | examples: ['a3bf90e006b2'] 17 | - id: runtime 18 | type: string 19 | brief: > 20 | このコンテナを管理しているコンテナランタイム 21 | examples: ['docker', 'containerd', 'rkt'] 22 | - id: image.name 23 | type: string 24 | brief: > 25 | コンテナイメージの名前 26 | examples: ['gcr.io/opentelemetry/operator'] 27 | - id: image.tag 28 | type: string 29 | brief: > 30 | コンテナイメージタグ 31 | examples: ['0.1'] 32 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/deployment_environment.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: deployment 3 | prefix: deployment 4 | brief: > 5 | ソフトウェアのデプロイ 6 | attributes: 7 | - id: environment 8 | type: string 9 | brief: > 10 | [デプロイ環境](https://en.wikipedia.org/wiki/Deployment_environment)の名前(別名:配置層) 11 | examples: ['staging', 'production'] 12 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/faas.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: faas_resource 3 | prefix: faas 4 | brief: > 5 | サーバーレスインスタンス 6 | attributes: 7 | - id: name 8 | type: string 9 | required: always 10 | brief: > 11 | 実行される関数名 12 | examples: ['my-function'] 13 | - id: id 14 | type: string 15 | required: always 16 | brief: > 17 | 実行される関数の一意なID 18 | note: > 19 | このフィールドは、例えばAWS Lambdaでは[ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)の値に、GCPではリソースのURIに、Azureでは[FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function)の値に対応しています。 20 | examples: ['arn:aws:lambda:us-west-2:123456789012:function:my-function'] 21 | - id: version 22 | type: string 23 | brief: > 24 | [バージョン属性](.../.../resource/semantic_conventions/README.md#version-attributes)で定義されている、実行される関数のバージョン文字列。 25 | examples: ['2.0.0'] 26 | - id: instance 27 | type: string 28 | brief: > 29 | 実行環境のID文字列。 30 | examples: ['my-function:instance-0001'] 31 | - id: max_memory 32 | type: int 33 | brief: > 34 | サーバーレス関数を実行する際のメモリをMiBで記述したもの 35 | note: > 36 | メモリが少なすぎるとJavaのAWS Lambda関数が正常に動作しなくなることがあるので、この属性を設定しておくことをお勧めします。AWS Lambda上では、環境変数 `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` がこの情報を提供します。 37 | examples: 128 38 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/host.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: host 3 | prefix: host 4 | brief: > 5 | ホストは一般的なコンピューティングインスタンスとして定義されます。 6 | attributes: 7 | - id: id 8 | type: string 9 | brief: > 10 | 一意のホスト ID。クラウドの場合、これはクラウドプロバイダーによって割り当てられた instance_id である必要があります。 11 | examples: ['opentelemetry-test'] 12 | - id: name 13 | type: string 14 | brief: > 15 | ホストの名前。Unix システムでは、hostname コマンドが返すもの、完全修飾されたホスト名、あるいはユーザが指定した別の名前が含まれます。 16 | examples: ['opentelemetry-test'] 17 | - id: type 18 | type: string 19 | brief: > 20 | ホストの種類。クラウドの場合は、マシンタイプである必要があります。 21 | examples: ['n1-standard-1'] 22 | - id: arch 23 | type: 24 | allow_custom_values: true 25 | members: 26 | - id: amd64 27 | value: 'amd64' 28 | brief: "AMD64" 29 | - id: arm32 30 | value: 'arm32' 31 | brief: "ARM32" 32 | - id: arm64 33 | value: 'arm64' 34 | brief: "ARM64" 35 | - id: ia64 36 | value: 'ia64' 37 | brief: "Itanium" 38 | - id: ppc32 39 | value: 'ppc32' 40 | brief: "32-bit PowerPC" 41 | - id: ppc64 42 | value: 'ppc64' 43 | brief: "64-bit PowerPC" 44 | - id: x86 45 | value: 'x86' 46 | brief: "32-bit x86" 47 | brief: > 48 | ホストシステムが動いているCPUアーキテクチャ 49 | - id: image.name 50 | type: string 51 | brief: > 52 | ホストがインスタンス化されたVMイメージまたはOSのインストール名。 53 | examples: ['infra-ami-eks-worker-node-7d4ec78312', 'CentOS-8-x86_64-1905'] 54 | - id: image.id 55 | type: string 56 | brief: > 57 | VM イメージ ID。クラウドの場合、この値はプロバイダのものです。 58 | examples: ['ami-07b06b442921831e5'] 59 | - id: image.version 60 | type: string 61 | brief: > 62 | [バージョン属性](README.md#version-attributes)で定義されているVMイメージのバージョン文字列。 63 | examples: ['0.1'] 64 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/k8s.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: k8s.cluster 3 | prefix: k8s.cluster 4 | brief: > 5 | Kubernetesクラスター 6 | attributes: 7 | - id: name 8 | type: string 9 | brief: > 10 | クラスターの名前。 11 | examples: ['opentelemetry-cluster'] 12 | 13 | - id: k8s.node 14 | prefix: k8s.node 15 | brief: > 16 | Kubernetes Nodeのオブジェクト 17 | attributes: 18 | - id: name 19 | type: string 20 | brief: > 21 | Nodeの名前 22 | examples: ['node-1'] 23 | - id: uid 24 | type: string 25 | brief: > 26 | NodeのUID 27 | examples: ['1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2'] 28 | 29 | - id: k8s.namespace 30 | prefix: k8s.namespace 31 | brief: > 32 | KubernetesのNamespace 33 | attributes: 34 | - id: name 35 | type: string 36 | brief: > 37 | Podが動作しているnamespaceの名前 38 | examples: ['default'] 39 | 40 | - id: k8s.pod 41 | prefix: k8s.pod 42 | brief: > 43 | KubernetesのPodのオブジェクト 44 | attributes: 45 | - id: uid 46 | type: string 47 | brief: > 48 | PodのUID 49 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 50 | - id: name 51 | type: string 52 | brief: > 53 | Podの名前 54 | examples: ['opentelemetry-pod-autoconf'] 55 | 56 | - id: k8s.container 57 | prefix: k8s.container 58 | brief: > 59 | [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates)の中のコンテナ。 60 | attributes: 61 | - id: name 62 | type: string 63 | brief: > 64 | PodTemplate の中のコンテナの名前 65 | examples: ['redis'] 66 | 67 | - id: k8s.replicaset 68 | prefix: k8s.replicaset 69 | brief: > 70 | KubernetesのReplicaSet オブジェクト 71 | attributes: 72 | - id: uid 73 | type: string 74 | brief: > 75 | ReplicaSetのUID 76 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 77 | - id: name 78 | type: string 79 | brief: > 80 | ReplicaSetの名前 81 | examples: ['opentelemetry'] 82 | 83 | - id: k8s.deployment 84 | prefix: k8s.deployment 85 | brief: > 86 | Kubernetes Deployment オブジェクト 87 | attributes: 88 | - id: uid 89 | type: string 90 | brief: > 91 | DeploymentのUID 92 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 93 | - id: name 94 | type: string 95 | brief: > 96 | Deploymentの名前 97 | examples: ['opentelemetry'] 98 | 99 | - id: k8s.statefulset 100 | prefix: k8s.statefulset 101 | brief: > 102 | Kubernetes StatefulSet オブジェクト 103 | attributes: 104 | - id: uid 105 | type: string 106 | brief: > 107 | StatefulSetのUID 108 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 109 | - id: name 110 | type: string 111 | brief: > 112 | StatefulSetの名前 113 | examples: ['opentelemetry'] 114 | 115 | - id: k8s.daemonset 116 | prefix: k8s.daemonset 117 | brief: > 118 | Kubernetes DaemonSet オブジェクト 119 | attributes: 120 | - id: uid 121 | type: string 122 | brief: > 123 | DaemonSetのUID 124 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 125 | - id: name 126 | type: string 127 | brief: > 128 | DaemonSetの名前 129 | examples: ['opentelemetry'] 130 | 131 | - id: k8s.job 132 | prefix: k8s.job 133 | brief: > 134 | Kubernetes Job オブジェクト 135 | attributes: 136 | - id: uid 137 | type: string 138 | brief: > 139 | JobのUID 140 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 141 | - id: name 142 | type: string 143 | brief: > 144 | Jobの名前 145 | examples: ['opentelemetry'] 146 | 147 | - id: k8s.cronjob 148 | prefix: k8s.cronjob 149 | brief: > 150 | Kubernetes CronJob オブジェクト 151 | attributes: 152 | - id: uid 153 | type: string 154 | brief: > 155 | CronJobのUID 156 | examples: ['275ecb36-5aa8-4c2a-9c47-d8bb681b9aff'] 157 | - id: name 158 | type: string 159 | brief: > 160 | CronJobの名前 161 | examples: ['opentelemetry'] 162 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/os.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: os 3 | prefix: os 4 | brief: > 5 | このリソースで表されるプロセスが実行されているオペレーティングシステム(OS) 6 | note: > 7 | 仮想化環境の場合、これはプロセスのOS、すなわち基礎となるホストではなく仮想化されたゲストのOSです。 8 | attributes: 9 | - id: type 10 | type: 11 | allow_custom_values: true 12 | members: 13 | - id: windows 14 | value: 'windows' 15 | brief: "Microsoft Windows" 16 | - id: linux 17 | value: 'linux' 18 | brief: "Linux" 19 | - id: darwin 20 | value: 'darwin' 21 | brief: "Apple Darwin" 22 | - id: freebsd 23 | value: 'freebsd' 24 | brief: "FreeBSD" 25 | - id: netbsd 26 | value: 'netbsd' 27 | brief: "NetBSD" 28 | - id: openbsd 29 | value: 'openbsd' 30 | brief: "OpenBSD" 31 | - id: dragonflybsd 32 | value: 'dragonflybsd' 33 | brief: "DragonFly BSD" 34 | - id: hpux 35 | value: 'hpux' 36 | brief: "HP-UX (Hewlett Packard Unix)" 37 | - id: aix 38 | value: 'aix' 39 | brief: "AIX (Advanced Interactive eXecutive)" 40 | - id: solaris 41 | value: 'solaris' 42 | brief: "Oracle Solaris" 43 | - id: z_os 44 | value: 'z_os' 45 | brief: "IBM z/OS" 46 | required: always 47 | brief: 'The operating system type.' 48 | - id: description 49 | type: string 50 | brief: > 51 | 人間が読める (解析を意図していない) OS のバージョン情報で、例えば `ver` や `lsb_release -a` コマンドで得られるような文字列です。 52 | examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] 53 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/process.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: process 3 | prefix: process 4 | brief: > 5 | OSのプロセス 6 | attributes: 7 | - id: pid 8 | type: int 9 | brief: > 10 | プロセスの識別子(PID) 11 | examples: [1234] 12 | - id: executable.name 13 | type: string 14 | required: 15 | conditional: "See below" 16 | brief: > 17 | 実行可能なプロセスの名前。Linuxベースのシステムでは、`proc/[pid]/status` の `Name` を設定できます。Windowsでは、`GetProcessImageFileNameW`のBaseNameを設定できます。 18 | examples: ['otelcol'] 19 | - id: executable.path 20 | type: string 21 | required: 22 | conditional: "See below" 23 | brief: > 24 | 実行可能なプロセスへのフルパス。Linuxベースのシステムでは、`proc/[pid]/exe` を設定できます。Windowsでは、`GetProcessImageFileNameW`の結果を設定できます。 25 | examples: ['/usr/bin/cmd/otelcol'] 26 | - id: command 27 | type: string 28 | required: 29 | conditional: "See below" 30 | brief: > 31 | プロセスを起動するために使用されたコマンド (すなわち、コマンド名)。Linuxベースのシステムでは、`proc/[pid]/cmdline`の0番目の文字列を設定できます。Windowsでは、`GetCommandLineW`から抽出した最初のパラメータを設定できます。 32 | examples: ['cmd/otelcol'] 33 | - id: command_line 34 | type: string 35 | required: 36 | conditional: "See below" 37 | brief: > 38 | プロセスを起動するために使用された完全なコマンドを1つの文字列で表します。Windowsでは、`GetCommandLineW`の結果を設定できます。モニタリングのためだけに構築する必要がある場合は設定しないでください。代わりに `process.command_args` を使ってください。 39 | examples: ['C:\cmd\otecol --config="my directory\config.yaml"'] 40 | - id: command_args 41 | type: string[] 42 | required: 43 | conditional: "See below" 44 | brief: > 45 | プロセスが受け取ったすべてのコマンド引数(コマンド/実行可能なもの自体を含む)。Linuxベースのシステム(およびprocfsをサポートする他のいくつかのUnix系システム)では、`proc/[pid]/cmdline`から抽出されたNULLで区切られた文字列のリストを設定できます。libcベースの実行ファイルの場合、これは `main` に渡される完全な argv ベクトルになります。 46 | examples: ['cmd/otecol', '--config=config.yaml'] 47 | - id: owner 48 | type: string 49 | brief: > 50 | プロセスを所有するユーザーのユーザー名。 51 | examples: 'root' 52 | - id: process.runtime 53 | prefix: process.runtime 54 | brief: > 55 | 監視対象の単一の(言語)ランタイムインスタンス。 56 | attributes: 57 | - id: name 58 | type: string 59 | brief: > 60 | このプロセスのランタイムの名前。コンパイルされたネイティブバイナリの場合、これはコンパイラの名前であるべきです[SHOULD]。 61 | examples: ['OpenJDK Runtime Environment'] 62 | - id: version 63 | type: string 64 | brief: > 65 | ランタイムが修正せずに返した、このプロセスのランタイムのバージョン。 66 | examples: '14.0.2' 67 | - id: description 68 | type: string 69 | brief: > 70 | プロセスのランタイムに関する追加の記述、例えば、ランタイム環境の特定のベンダのカスタマイズなど。 71 | examples: 'Eclipse OpenJ9 Eclipse OpenJ9 VM openj9-0.21.0' 72 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/service.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: service 3 | prefix: service 4 | brief: > 5 | サービスのインスタンス 6 | attributes: 7 | - id: name 8 | type: string 9 | required: always 10 | brief: > 11 | サービスの論理名。 12 | note: > 13 | 水平方向にスケールされたサービスのすべてのインスタンスに対して同じ値を指定しなければなりません(MUST)。値が指定されていない場合、SDKは `unknown_service:` を [`process.executeable.name`](process.md#process) で連結したもの、例えば `unknown_service:bash` などにフォールバックしなければなりません(MUST)。もし `process.executeable.name` が利用できない場合は、`unknown_service` を設定しなければなりません(MUST)。 14 | examples: ["shoppingcart"] 15 | - id: namespace 16 | type: string 17 | brief: > 18 | `service.name`の名前空間。 19 | note: > 20 | サービスのグループを区別するのに役立つ意味を持つ文字列値。例えば、サービスのグループを所有するチーム名などです。 21 | `service.name` は同じ名前空間内で一意であることが期待されます。`service.namespace` がResourceに指定されていない場合、`service.name` は明示的な名前空間が定義されていないすべてのサービスに対して一意であることが期待されます (つまり、空の/未指定の名前空間は単に有効な名前空間の1つに過ぎません)。長さ0の名前空間文字列は、未指定の名前空間と同じとみなされます。 22 | examples: ["Shop"] 23 | - id: instance.id 24 | type: string 25 | brief: > 26 | サービスインスタンスを表すID文字列。 27 | note: > 28 | 同じ `service.namespace,service.name` のペアの各インスタンスに対して一意でなければなりません(言い換えれば、`service.namespace,service.name,service.instance.id` の一組はグローバルに一意でなければなりません(MUST)。IDは、同時に存在する同じサービスのインスタンスを区別するのに役立ちます(例えば、水平方向にスケーリングされたサービスのインスタンス)。ID は永続的で、サービスインスタンスの寿命の間は同じであることが望ましいですが、サービスの重要な寿命イベント(サービスの再起動など)の間に ID が変化しても構いません。サービスがこの属性の値として使用できる固有のユニークなIDを持たない場合、ランダムなバージョン1またはバージョン4のRFC 4122 UUIDを生成することが推奨されます(再現可能なUUIDを目指すサービスはバージョン5を使用することもできます。より多くの推奨事項についてはRFC 4122を参照してください)。 29 | examples: ["627cc493-f310-47de-96bd-71410b7dec09"] 30 | - id: version 31 | type: string 32 | brief: > 33 | サービスAPIまたは実装のバージョン文字列。 34 | examples: ["2.0.0"] 35 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/telemetry.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: telemetry 3 | prefix: telemetry 4 | brief: > 5 | 計装ライブラリで記録されたデータをキャプチャするために使用されるテレメトリSDKです。 6 | attributes: 7 | - id: sdk.name 8 | type: string 9 | brief: > 10 | 上記で定義したテレメトリSDKの名前。 11 | examples: ["opentelemetry"] 12 | - id: sdk.language 13 | type: 14 | allow_custom_values: true 15 | members: 16 | - id: cpp 17 | value: "cpp" 18 | - id: dotnet 19 | value: "dotnet" 20 | - id: erlang 21 | value: "erlang" 22 | - id: go 23 | value: "go" 24 | - id: java 25 | value: "java" 26 | - id: nodejs 27 | value: "nodejs" 28 | - id: php 29 | value: "php" 30 | - id: python 31 | value: "python" 32 | - id: ruby 33 | value: "ruby" 34 | - id: webjs 35 | value: "webjs" 36 | brief: > 37 | テレメトリSDKの言語。 38 | - id: sdk.version 39 | type: string 40 | brief: > 41 | テレメトリSDKのバージョン文字列。 42 | examples: ["1.2.3"] 43 | - id: auto.version 44 | type: string 45 | brief: > 46 | 使用されている場合は、自動インストルメンテーションエージェントのバージョン文字列。 47 | examples: ["1.2.3"] 48 | -------------------------------------------------------------------------------- /specification/semantic_conventions/resource/webengine.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: webengine_resource 3 | prefix: webengine 4 | brief: > 5 | アプリケーション・コードを実行するパッケージ・ソフトウェアを記述するリソース。Webエンジンは、通常、process.runtimeを使用して実行されます。 6 | attributes: 7 | - id: name 8 | type: string 9 | required: always 10 | brief: > 11 | Webエンジンの名前 12 | examples: ['WildFly'] 13 | - id: version 14 | type: string 15 | brief: > 16 | Webエンジンのバージョン 17 | examples: ['21.0.0'] 18 | - id: description 19 | type: string 20 | brief: > 21 | Webエンジンの追加説明(詳細なバージョンとエディション情報など) 22 | examples: ['WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final'] -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/exception.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: exception 3 | prefix: exception 4 | brief: > 5 | このドキュメントでは、Spanに関連する単一の例外を報告するための属性を定義しています。 6 | attributes: 7 | - id: type 8 | type: string 9 | brief: > 10 | 例外のタイプ(該当する場合は、完全修飾クラス名)。例外の動的な型をサポートする言語では、静的型よりも動的型を優先すべきです。 11 | examples: ["java.net.ConnectException","OSError"] 12 | - id: message 13 | type: string 14 | brief: 例外のメッセージ 15 | examples: ["Division by zero","Can't convert 'int' object to str implicitly"] 16 | - id: stacktrace 17 | type: string 18 | brief: > 19 | スタックトレースは、言語ランタイムの自然な表現の文字列です。この表現は各言語のSIGが決定し、文書化することになっています。 20 | examples: 'Exception in thread "main" java.lang.RuntimeException: Test exception\n 21 | at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n 22 | at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n 23 | at com.example.GenerateTrace.main(GenerateTrace.java:5)' 24 | - id: escaped 25 | type: boolean 26 | brief: > 27 | 例外がSpanの範囲を逸脱していることが分かっている場所で例外イベントが記録された場合、trueに設定するべきです(SHOULD)。 28 | note: |- 29 | 例外が論理的に"飛行中(in flight)"である間にSpanが終了した場合、例外はSpanの範囲から脱出(または離脱)したとみなされます。これは、言語によっては実際に"飛行中"かもしれませんが(例:Pythonで例外がContext managerの`__exit__`メソッドに渡された場合)、ほとんどの言語では例外を記録した時点で捕捉されるのが普通です。 30 | 例外が投げられた時点で、その例外がSpanのスコープから外れるかどうかを判断することは通常できません。しかし、[上記の例](#exception-end-example)のように、Spanを終了する直前にアクティブな例外があるかどうかをチェックすれば、例外がエスケープされるかどうかを知ることは簡単です。 31 | これによると、`exception.escaped` 属性が設定されていなかったり、false に設定されていたりしても、例外がSpanのスコープを抜け出す可能性があります。これは、例外が抜け出すかどうかがはっきりしない時点でイベントが記録されている可能性があるからです。 32 | constraints: 33 | - any_of: 34 | - "exception.type" 35 | - "exception.message" 36 | -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/faas.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: faas_span 3 | prefix: faas 4 | brief: > 5 | このセマンティクス規約は、サーバーのプロビジョニングや管理を行わずに実行される関数(サーバーレス関数やFunction as a Service(FaaS)とも呼ばれる)のインスタンスをSpanで記述します。 6 | attributes: 7 | - id: trigger 8 | required: 9 | conditional: > 10 | FaaSインスタンスでは、着信時にfaas.trigger属性を設定しなければなりません(MUST)。FaaSインスタンスを起動しているクライアントは、クライアントに知られている場合、発信される起動に`faas.trigger`を設定しなければなりません(MUST)。例えば、トランスポートレイヤーがFaaSクライアントフレームワークで抽象化されていて、その設定にアクセスできない場合は、この限りではありません。 11 | brief: '関数が実行されるトリガーのタイプ。' 12 | type: 13 | allow_custom_values: false 14 | members: 15 | - id: datasource 16 | value: 'datasource' 17 | brief: 'データベースやファイルシステムの読み取り/書き込みなど、データソースの操作に対する応答の関数。' 18 | - id: http 19 | value: 'http' 20 | brief: '受信したHTTPリクエストへの応答の関数。' 21 | - id: pubsub 22 | value: 'pubsub' 23 | brief: 'メッセージングシステムにメッセージが送信されたときに実行される設定の関数。' 24 | - id: timer 25 | value: 'timer' 26 | brief: '定期的に実行されるように予定されている関数。' 27 | - id: other 28 | value: 'other' 29 | brief: '他に該当するものがない関数' 30 | - id: execution 31 | type: string 32 | brief: '現在実行されている関数の実行ID。' 33 | examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28' 34 | 35 | - id: faas_span.datasource 36 | prefix: faas.document 37 | extends: faas_span 38 | brief: > 39 | データベースやファイルシステムの読み書きなど、データソースの操作に反応して起動するFaaSのセマンティック規約。 40 | attributes: 41 | - id: collection 42 | type: string 43 | required: always 44 | brief: > 45 | トリガー操作が行われたソースの名前。例えば、Cloud StorageやS3であればバケット名、Cosmos DBであればデータベース名に対応します。 46 | examples: ['myBucketName', 'myDbName'] 47 | - id: operation 48 | required: always 49 | type: 50 | allow_custom_values: true 51 | members: 52 | - id: insert 53 | value: 'insert' 54 | brief: '新しいオブジェクトが作成されたとき' 55 | - id: edit 56 | value: 'edit' 57 | brief: 'オブジェクトが変更されたとき' 58 | - id: delete 59 | value: 'delete' 60 | brief: 'オブジェクトが削除されたとき' 61 | brief: 'データに対して行われた操作の種類を記述します。' 62 | - id: time 63 | type: string 64 | required: always 65 | brief: > 66 | データにアクセスした時刻を[ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)形式で、[UTC](https://www.w3.org/TR/NOTE-datetime)で表した文字列。 67 | examples: "2020-01-23T13:47:06Z" 68 | - id: name 69 | type: string 70 | brief: > 71 | 操作の対象となるドキュメント名/テーブル名。例えば、クラウドストレージやS3ではファイル名、Cosmos DBではテーブル名となります。 72 | examples: ["myFile.txt", "myTableName"] 73 | 74 | - id: faas_span.http 75 | extends: faas_span 76 | brief: > 77 | TODO: databaseの話になってるのはtypo? 78 | Semantic Convention for FaaS triggered as a response to some data 79 | source operation such as a database or filesystem read/write. 80 | constraints: 81 | - include: http.server 82 | 83 | - id: faas_span.pubsub 84 | extends: faas_span 85 | brief: > 86 | メッセージングシステムにメッセージが送信されたときに実行されるFaaSセットのセマンティック規約。 87 | constraints: 88 | - include: messaging 89 | 90 | - id: faas_span.timer 91 | extends: faas_span 92 | prefix: faas 93 | brief: > 94 | 定期的に実行されることが予定されているFaaSのセマンティック規約。 95 | attributes: 96 | - id: time 97 | type: string 98 | required: always 99 | brief: > 100 | [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)形式で、[UTC](https://www.w3.org/TR/NOTE-datetime)で表現された関数の起動時間を含む文字列です 101 | examples: "2020-01-23T13:47:06Z" 102 | - id: cron 103 | type: string 104 | brief: > 105 | スケジュール期間を[Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm)として含む文字列。 106 | examples: "0/5 * * * ? *" 107 | 108 | - id: faas_span.in 109 | extends: faas_span 110 | span_kind: server 111 | prefix: faas 112 | brief: > 113 | 受信するFaaS Spanの追加属性 114 | attributes: 115 | - id: coldstart 116 | type: boolean 117 | brief: > 118 | サーバーレス機能が初めて実行された場合(コールドスタート)に真となる真偽値。 119 | 120 | - id: faas_span.out 121 | extends: faas_span 122 | span_kind: client 123 | prefix: faas 124 | brief: > 125 | 発信するFaaS Spanの追加属性 126 | attributes: 127 | - id: invoked_name 128 | type: string 129 | required: always 130 | brief: > 131 | 呼び出された関数の名前です。 132 | note: > 133 | 呼び出された関数のリソース属性 `faas.name` と同じ値にすべきです(SHOULD)。 134 | examples: 'my-function' 135 | - id: invoked_provider 136 | type: 137 | allow_custom_values: true 138 | members: 139 | - id: AWS 140 | value: 'aws' 141 | brief: 'Amazon Web Services' 142 | - id: Azure 143 | value: 'azure' 144 | brief: 'Microsoft Azure' 145 | - id: GCP 146 | value: 'gcp' 147 | brief: 'Google Cloud Platform' 148 | required: always 149 | brief: > 150 | 呼び出された関数のクラウドプロバイダー。 151 | note: > 152 | 呼び出された関数のリソース属性である `cloud.provider` と同じ値にすべきです(SHOULD)。 153 | examples: 'aws' 154 | - id: invoked_region 155 | type: string 156 | required: 157 | conditional: > 158 | AWSやGCPなどの一部のクラウドプロバイダーでは、関数を一意に識別するためにその関数がホストされているリージョンが不可欠な情報であり、またエンドポイントの一部でもあります。リージョンは呼び出されるエンドポイントの一部であるため、クライアントは常にリージョンを知っています。このような場合には、`faas.invoked_region` を適宜設定しなければなりません(MUST)。リージョンがクライアントに知られていない場合や、呼び出された関数を識別するのに必要ない場合は、`faas.invoked_region`の設定は任意です。 159 | brief: > 160 | 呼び出された関数が動いているリージョン 161 | note: > 162 | 呼び出された関数のリソース属性である `cloud.region` と同じ値にすべきです(SHOULD)。 163 | examples: 'eu-central-1' 164 | -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/general.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: network 3 | prefix: net 4 | brief: > 5 | これらの属性は、ネットワーク関連のあらゆる操作に使用できます。 6 | attributes: 7 | - id: transport 8 | type: 9 | allow_custom_values: false 10 | members: 11 | - id: ip_tcp 12 | value: "ip_tcp" 13 | - id: ip_udp 14 | value: "ip_udp" 15 | - id: ip 16 | value: "ip" 17 | brief: '他の IP-based プロトコル' 18 | - id: unix 19 | value: "unix" 20 | brief: 'Unix Domain socket. 下記参照' 21 | - id: pipe 22 | value: "pipe" 23 | brief: 'Named あるいは anonymous pipe. 下記注釈参照' 24 | - id: inproc 25 | value: "inproc" 26 | brief: 'In-process communication.' 27 | note: > 28 | 通常、ネットワークの属性が期待される場合に、「実際の」ネットワークプロトコルを使用しないin-processの通信のみが存在することを示します。通常、この場合、他のネットワーク属性はすべて省くことができます。 29 | - id: other 30 | value: "other" 31 | brief: 'その他 (non IP-based).' 32 | brief: > 33 | Transport protocol used. 下記注釈参照。 34 | examples: 'ip_tcp' 35 | - id: peer.ip 36 | type: string 37 | brief: > 38 | 相手のリモートアドレス(IPv4ではドット10進数、IPv6では[RFC5952](https://tools.ietf.org/html/rfc5952) 39 | examples: '127.0.0.1' 40 | - id: peer.port 41 | type: int 42 | brief: 'リモートのポート番号' 43 | examples: [80, 8080, 443] 44 | - id: peer.name 45 | type: string 46 | brief: 'リモートのホスト名あるいは類似の文字列。下記注釈参照' 47 | examples: 'example.com' 48 | - id: host.ip 49 | type: string 50 | brief: '`net.peer.ip`と同じですが、ホストのIPを指定します。マルチIPのホストの場合に便利です。' 51 | examples: '192.168.0.1' 52 | - id: host.port 53 | type: int 54 | brief: '`net.peer.port`と同じですが、ホストのポートを指定します。' 55 | examples: 35555 56 | - id: host.name 57 | type: string 58 | brief: 'ローカルのホスト名あるいは類似の文字列 下記注釈参照' 59 | examples: 'localhost' 60 | - id: peer 61 | prefix: peer 62 | brief: "あるリモートサービスにアクセスする操作" 63 | attributes: 64 | - id: service 65 | type: string 66 | brief: > 67 | リモートサービスの[`service.name`](../../resource/semantic_conventions/README.md#service)を指定します。リモートサービスの実際の `service.name` リソース属性があれば、それと等しくすべきです(SHOULD)。 68 | examples: "AuthTokenCache" 69 | - id: identity 70 | prefix: enduser 71 | brief: > 72 | これらの属性は、認証および/または認可されたエンドユーザーとのあらゆる操作に使用できます。 73 | attributes: 74 | - id: id 75 | type: string 76 | brief: > 77 | システム外からのインバウンドリクエストのアクセストークンまたは[Authorization](https://tools.ietf.org/html/rfc7235#section-4.2)ヘッダーから抽出したユーザー名またはclient_id。 78 | examples: 'username' 79 | - id: role 80 | type: string 81 | brief: 'トークンやアプリケーションのセキュリティコンテキストから抽出された、クライアントがリクエストを行う際の実際の役割/想定される役割。' 82 | examples: 'admin' 83 | - id: scope 84 | type: string 85 | brief: > 86 | トークンやアプリケーションのセキュリティコンテキストから抽出された、クライアントが現在所有しているスコープや付与された権限。この値は、[OAuth 2.0 Access Token](https://tools.ietf.org/html/rfc6749#section-3.3)に関連付けられたスコープ、または[SAML 2.0 Assertion](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)の属性値に由来するものです。 87 | examples: 'read:message, write:files' 88 | - id: thread 89 | prefix: thread 90 | brief: > 91 | これらの属性は、Spanを開始したスレッドに関する情報を保存するためのあらゆる操作に使用できます。 92 | attributes: 93 | - id: id 94 | type: int 95 | brief: > 96 | 現在の「管理された」スレッドID(OSのスレッドIDとは異なります)。 97 | examples: 42 98 | - id: name 99 | type: string 100 | brief: > 101 | 現在のスレッド名 102 | examples: main 103 | - id: code 104 | prefix: code 105 | brief: > 106 | これらの属性により、コードユニットを報告することができます。その結果、Spanに関するより多くの情報を提供することができます。 107 | attributes: 108 | - id: function 109 | type: string 110 | brief: > 111 | メソッド名、関数名、またはそれに相当するもの(通常はコードユニット名の最右端)。 112 | examples: serveRequest 113 | - id: namespace 114 | type: string 115 | brief: > 116 | `code.function`が定義されている「名前空間」です。通常は、修飾されたクラスやモジュールの名前で、 `code.namespace` + 何かの区切り文字 + `code.function` がコードユニットの一意な識別子になります。 117 | examples: com.example.MyHttpService 118 | - id: filepath 119 | type: string 120 | brief: > 121 | コードユニットを可能な限り一意に識別するためのソースコードファイル名(絶対ファイルパスが望ましい)。 122 | examples: /usr/local/MyApplication/content_root/app/index.php 123 | - id: lineno 124 | type: int 125 | brief: > 126 | `code.filepath` の中で、操作を表すのに最適な行番号です。これは `code.function` で指定されたコードユニット内を指すべきです。 127 | examples: 42 128 | -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/http.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: http 3 | prefix: http 4 | brief: 'この文書では、HTTPクライアントおよびサーバーのSpansのセマンティック規約を定義しています。' 5 | note: > 6 | これらの規約は、httpとhttpsのスキームや、1.1、2、SPDYなどの様々なHTTPバージョンに使用することができます。 7 | attributes: 8 | - id: method 9 | type: string 10 | required: always 11 | brief: 'HTTPリクエストメソッド' 12 | examples: ["GET", "POST", "HEAD"] 13 | - id: url 14 | type: string 15 | brief: > 16 | `scheme://host[:port]/path?query[#fragment]`という形式の完全なHTTPリクエストURLです。 17 | 通常、このフラグメントはHTTPでは送信されませんが、知られている場合は、それにもかかわらず含める必要があります。 18 | note: > 19 | `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. 20 | In such case the attribute's value should be `https://www.example.com/`. 21 | examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] 22 | - id: target 23 | type: string 24 | brief: 'HTTPリクエスト行またはそれに相当するもので渡される、完全なリクエストターゲット。' 25 | examples: ['/path/12314/?q=ddds#123'] 26 | - id: host 27 | type: string 28 | brief: > 29 | [HTTP host ヘッダー](https://tools.ietf.org/html/rfc7230#section-5.4)の値です。 30 | ヘッダーが空の場合、または存在しない場合、この属性は同じである必要があります。 31 | examples: ['www.example.org'] 32 | - id: scheme 33 | type: string 34 | brief: '使用するプロトコルを示すURIスキーム' 35 | examples: ["http", "https"] 36 | - id: status_code 37 | type: int 38 | required: 39 | conditional: 受信/送信された場合に限ります。 40 | brief: '[HTTP レスポンス status code](https://tools.ietf.org/html/rfc7231#section-6).' 41 | examples: [200] 42 | - id: flavor 43 | type: 44 | # Default value: `true`. If false, it helps the code gen tool to 45 | # encode checks that only accept the listed values. 46 | allow_custom_values: true 47 | members: 48 | - id: HTTP_1_0 49 | value: '1.0' 50 | brief: 'HTTP 1.0' 51 | - id: HTTP_1_1 52 | value: '1.1' 53 | brief: 'HTTP 1.1' 54 | - id: HTTP_2_0 55 | value: '2.0' 56 | brief: 'HTTP 2' 57 | - id: SPDY 58 | value: 'SPDY' 59 | brief: 'SPDY protocol.' 60 | - id: QUIC 61 | value: 'QUIC' 62 | brief: 'QUIC protocol.' 63 | brief: '使われているHTTP protocolの種類' 64 | note: > 65 | `net.transport` が指定されていない場合は、`IP.TCP`と仮定できます。ただし、`http.flavor` が `QUIC` の場合は、`IP.UDP` を想定しています。 66 | examples: ['1.0'] 67 | - id: user_agent 68 | type: string 69 | brief: 'クライアントが送信した[HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3)ヘッダの値。' 70 | examples: ['CERN-LineMode/2.15 libwww/2.17b3'] 71 | - id: request_content_length 72 | type: int 73 | brief: > 74 | リクエストのペイロードボディのサイズ(バイト)です。これは、ヘッダーを除いて転送されたバイト数で、[Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2)ヘッダーとして表示されることが多いですが、必ずしもそうではありません。トランスポートエンコーディングを使用するリクエストでは、これは圧縮されたサイズでなければなりません。 75 | examples: 3495 76 | - id: request_content_length_uncompressed 77 | type: int 78 | brief: > 79 | トランスポートデコーディング後の、圧縮されていないリクエストペイロードボディのサイズです。トランスポートエンコーディングを使用しない場合は設定されません。 80 | examples: 5493 81 | - id: response_content_length 82 | type: int 83 | brief: > 84 | レスポンスペイロードボディのサイズ(バイト)です。これは、ヘッダーを除いて転送されたバイト数で、[Content-Length](https://tools.ietf.org/html/rfc7230#section-3.3.2)ヘッダーとして表示されることが多いですが、必ずしもそうではありません。トランスポートエンコーディングを使用するリクエストでは、これは圧縮されたサイズでなければなりません。 85 | examples: 3495 86 | - id: response_content_length_uncompressed 87 | type: int 88 | brief: > 89 | トランスポートデコーディング後の、圧縮されていないレスポンスペイロードボディのサイズです。トランスポートエンコーディングを使用しない場合は設定されません。 90 | examples: 5493 91 | constraints: 92 | - include: network 93 | 94 | - id: http.client 95 | prefix: http 96 | extends: http 97 | span_kind: client 98 | brief: 'HTTP Clientのセマンティック規約' 99 | constraints: 100 | - any_of: 101 | - [http.url] 102 | - [http.scheme, http.host, http.target] 103 | - [http.scheme, net.peer.name, net.peer.port, http.target] 104 | - [http.scheme, net.peer.ip, net.peer.port, http.target] 105 | 106 | - id: http.server 107 | prefix: http 108 | extends: http 109 | span_kind: server 110 | brief: 'HTTP Serverのセマンティック規約' 111 | attributes: 112 | - id: server_name 113 | type: string 114 | brief: > 115 | 一致したバーチャルホストのプライマリサーバー名です。これは設定で取得する必要があります。 116 | そのような設定が得られない場合は、この属性を設定してはいけません(MUST NOT)(`net.host.name`を代わりに使用する必要があります)。 117 | note: > 118 | `http.url`は通常、サーバー側では容易に入手できませんが、他の情報から煩雑で時には損失を伴うプロセスで組み立てなければなりません(例:open-telemetry/opentelemetry-python/pull/148を参照)。 119 | そのため、利用可能な生データを提供することが望ましいです。 120 | examples: ['example.com'] 121 | - id: route 122 | type: string 123 | brief: > 124 | マッチしたルート(パステンプレート) 125 | examples: '/users/:userID?' 126 | - id: client_ip 127 | type: string 128 | brief: > 129 | すべてのプロキシの背後にあるオリジナルのクライアントのIPアドレス(既知の場合)(例:[X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)より) 130 | note: > 131 | これは必ずしも`net.peer.ip`と同じではありません。`net.peer.ip`はネットワークレベルのピアを特定するもので、プロキシである可能性もあります。 132 | examples: '83.164.160.102' 133 | constraints: 134 | - any_of: 135 | - [http.scheme, http.host, http.target] 136 | - [http.scheme, http.server_name, net.host.port, http.target] 137 | - [http.scheme, net.host.name, net.host.port, http.target] 138 | - [http.url] 139 | -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/messaging.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: messaging 3 | prefix: messaging 4 | brief: > 5 | このドキュメントでは、メッセージングシステムで使用される属性を定義しています。 6 | attributes: 7 | - id: system 8 | type: string 9 | required: always 10 | brief: 'メッセージングシステムを識別するための文字列' 11 | examples: ['kafka', 'rabbitmq', 'activemq', 'AmazonSQS'] 12 | - id: destination 13 | type: string 14 | required: always 15 | brief: > 16 | メッセージの宛先名です。これは、Span名と同じかもしれませんが、それでも必要です。 17 | examples: ['MyQueue', 'MyTopic'] 18 | - id: destination_kind 19 | type: 20 | allow_custom_values: false 21 | members: 22 | - id: queue 23 | value: "queue" 24 | brief: "メッセージはQueueに送られる" 25 | - id: topic 26 | value: "topic" 27 | brief: "メッセージはTopicに送られる" 28 | required: 29 | conditional: 'メッセージの宛先が `queue` または `topic` の場合にのみ必要です。' 30 | brief: 'メッセージの宛先の種類' 31 | - id: temp_destination 32 | type: boolean 33 | required: 34 | conditional: '欠落している場合は、偽であると見なされます' 35 | brief: 'メッセージの送信先が一時的なものである場合に真となる真偽値' 36 | - id: protocol 37 | type: string 38 | brief: 'トランスポートプロトコルの名前' 39 | examples: ['AMQP', 'MQTT'] 40 | - id: protocol_version 41 | type: string 42 | brief: 'トランスポートプロトコルのバージョン' 43 | examples: '0.9.1' 44 | - id: url 45 | type: string 46 | brief: '接続文字列' 47 | examples: ['tibjmsnaming://localhost:7222', 'https://queue.amazonaws.com/80398EXAMPLE/MyQueue'] 48 | - id: message_id 49 | type: string 50 | brief: 'メッセージングシステムがメッセージの識別子として使用する値で、文字列で表されます。' 51 | examples: '452a7c7c7c7048c2f887f61572b18fc2' 52 | - id: conversation_id 53 | type: string 54 | brief: > 55 | メッセージが属する会話を識別する[会話ID](#conversations)を文字列で表したもの。"Correlation ID"と呼ばれることもあります。 56 | examples: 'MyConversationId' 57 | - id: message_payload_size_bytes 58 | type: int 59 | brief: > 60 | メッセージのペイロードの(圧縮されていない)サイズをバイト単位で示したものです。また、圧縮されたペイロード・サイズと非圧縮のペイロード・サイズのどちらが報告されるかが不明な場合にも、この属性を使用します。 61 | examples: 2738 62 | - id: message_payload_compressed_size_bytes 63 | type: int 64 | brief: 'メッセージのペイロードの圧縮サイズ(バイト)です。' 65 | examples: 2048 66 | - ref: net.peer.name 67 | note: > 68 | これは、この特定のメッセージを送受信するブローカー(または他のネットワークレベルのピア)のIP/ホスト名でなければなりません。 69 | required: 70 | conditional: 利用可能な場合 71 | - ref: net.peer.ip 72 | tag: connection-level 73 | required: 74 | conditional: 利用可能な場合 75 | constraints: 76 | - include: network 77 | 78 | - id: messaging.producer 79 | prefix: messaging 80 | extends: messaging 81 | span_kind: producer 82 | brief: 'メッセージングシステムに送信されるメッセージのプロデューサーのためのセマンティック規約' 83 | 84 | - id: messaging.producer.synchronous 85 | prefix: messaging 86 | extends: messaging 87 | span_kind: client 88 | brief: > 89 | メッセージを生成し、同期的に応答を待つメッセージングシステムのクライアントのためのセマンティック規約。 90 | 91 | - id: messaging.consumer 92 | prefix: messaging 93 | extends: messaging 94 | span_kind: consumer 95 | brief: 'メッセージングシステムから受信したメッセージの消費者のためのセマンティック規約' 96 | attributes: 97 | - id: operation 98 | type: 99 | allow_custom_values: false 100 | members: 101 | - id: receive 102 | value: "receive" 103 | - id: process 104 | value: "process" 105 | brief: > 106 | 上記の[操作名](#operation-names)セクションで定義されているメッセージ消費の種類を識別する文字列です。操作が "send"の場合、この属性は設定してはいけません(MUST NOT)。なぜなら、この場合、操作はspan kindから推測できるからです。 107 | 108 | - id: messaging.consumer.synchronous 109 | prefix: messaging 110 | extends: messaging.consumer 111 | span_kind: server 112 | brief: > 113 | メッセージングシステムから受信したメッセージを消費し、常にそのメッセージのProducerに向けた返信を返すサーバーのためのセマンティックな規約 114 | 115 | - id: messaging.rabbitmq 116 | prefix: messaging.rabbitmq 117 | extends: messaging 118 | brief: > 119 | RabbitMQのための属性 120 | attributes: 121 | - id: routing_key 122 | type: string 123 | required: 124 | conditional: 空でなければ 125 | brief: > 126 | RabbitMQのメッセージルーティングキー。 127 | examples: 'myKey' 128 | 129 | - id: messaging.kafka 130 | prefix: messaging.kafka 131 | extends: messaging 132 | brief: > 133 | Apache Kafkaのための属性 134 | attributes: 135 | - id: message_key 136 | type: string 137 | brief: > 138 | Kafkaのメッセージキーは、同じメッセージが同じパーティションで処理されるようにグループ化するために使用されます。メッセージキーは、`messaging.message_id` とは異なり、一意ではありません。キーが `null` の場合、この属性は設定してはいけません (MUST NOT)。 139 | note: > 140 | キータイプが文字列でない場合は、その文字列表現を属性に与える必要があります。キーが曖昧でない正規の文字列形式を持たない場合、その値を含めてはいけません。 141 | examples: 'myKey' 142 | - id: consumer_group 143 | type: string 144 | brief: > 145 | メッセージを処理しているKafka Consumerグループの名前。Producerではなく、Consumerにのみ適用されます。 146 | examples: 'my-group' 147 | - id: client_id 148 | type: string 149 | brief: > 150 | メッセージを処理しているConsumerまたはProducerのClient Id。 151 | examples: 'client-5' 152 | - id: partition 153 | type: int 154 | brief: > 155 | メッセージの送信先となるパーティション。 156 | examples: 2 157 | - id: tombstone 158 | type: boolean 159 | required: 160 | conditional: '欠落している場合は、偽であると見なされます' 161 | brief: 'メッセージがTombstoneである場合に真となる真偽値' 162 | -------------------------------------------------------------------------------- /specification/semantic_conventions/trace/rpc.yaml: -------------------------------------------------------------------------------- 1 | groups: 2 | - id: rpc 3 | prefix: rpc 4 | brief: 'この文書では、リモートプロシージャコールのセマンティック規約を定義しています' 5 | attributes: 6 | - id: system 7 | type: string 8 | required: always 9 | brief: 'リモーションシステムを識別する文字列' 10 | examples: ["grpc", "java_rmi", "wcf"] 11 | - id: service 12 | type: string 13 | required: 14 | conditional: "いいえ、しかし推奨です" 15 | brief: '呼び出されるサービスのフルネーム(該当する場合は、パッケージ名も含む)' 16 | examples: "myservice.EchoService" 17 | - id: method 18 | type: string 19 | required: 20 | conditional: "いいえ、しかし推奨です" 21 | brief: '呼び出されるメソッドの名前は、Span名の$method部分と等しくなければなりません。' 22 | examples: "exampleMethod" 23 | - ref: net.peer.ip 24 | - ref: net.peer.name 25 | - ref: net.peer.port 26 | required: 27 | conditional: "下記参照" 28 | - ref: net.transport 29 | required: 30 | conditional: "下記参照" 31 | constraints: 32 | - any_of: 33 | - net.peer.ip 34 | - net.peer.name 35 | - include: network 36 | - id: rpc.grpc 37 | prefix: rpc.grpc 38 | extends: rpc 39 | brief: 'gRPCの技術固有の属性' 40 | attributes: 41 | - id: status_code 42 | type: 43 | members: 44 | - id: OK 45 | value: 0 46 | - id: CANCELLED 47 | value: 1 48 | - id: UNKNOWN 49 | value: 2 50 | - id: INVALID_ARGUMENT 51 | value: 3 52 | - id: DEADLINE_EXCEEDED 53 | value: 4 54 | - id: NOT_FOUND 55 | value: 5 56 | - id: ALREADY_EXISTS 57 | value: 6 58 | - id: PERMISSION_DENIED 59 | value: 7 60 | - id: RESOURCE_EXHAUSTED 61 | value: 8 62 | - id: FAILED_PRECONDITION 63 | value: 9 64 | - id: ABORTED 65 | value: 10 66 | - id: OUT_OF_RANGE 67 | value: 11 68 | - id: UNIMPLEMENTED 69 | value: 12 70 | - id: INTERNAL 71 | value: 13 72 | - id: UNAVAILABLE 73 | value: 14 74 | - id: DATA_LOSS 75 | value: 15 76 | - id: UNAUTHENTICATED 77 | value: 16 78 | required: always 79 | brief: "gRPCリクエストの[numeric status code](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md)です" 80 | examples: [0, 1, 16] 81 | -------------------------------------------------------------------------------- /specification/semantic_conventions/version.properties: -------------------------------------------------------------------------------- 1 | version=1 2 | -------------------------------------------------------------------------------- /specification/specification/common/common.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 共通な仕様のコンセプト 6 | 7 | **Status**: [Stable, Feature-freeze](../document-status.md) 8 | 9 |
10 | 11 | 目次 12 | 13 | 14 | 17 | 18 | - [属性](#属性) 19 | 20 |
21 | 22 | 25 | 26 | ## 属性 27 | 28 | 31 | 32 | 属性は、0個以上のキーと値のペアのリストです。`アトリビュート`は以下のプロパティを持たなければなりません(MUST)。 33 | 34 | 42 | 43 | - 属性のキーは、非`null`かつ非空の文字列でなければなりません(MUST)。 44 | - 属性の値は、下のいずれかの値です: 45 | - プリミティブタイプ:string、boolean、倍精度浮動小数点(IEEE 754-1985)、符号付き64ビット整数 46 | - プリミティブ型の値の配列。配列内はすべて同じ型でなければならない(MUST)。つまり、異なるタイプの値を含んではならない(MUST NOT)。配列値をネイティブにサポートしていないプロトコルでは、そのような値はJSON文字列として表現されるべきです(SHOULD)。 47 | 48 | 53 | 54 | ゼロの数値、空の文字列、または空の配列を表現する属性値は、意味があるとみなされ、保存されてProcessorやExporterに渡されなければなりません(MUST)。 55 | 56 | 60 | 61 | `null`の属性値は有効ではなく、`null`の値を設定しようとするのは未定義の動作です。 62 | 63 | 75 | 76 | 配列の中に `null` 値を入れてはいけません(SHOULD NOT)。しかし、`null` 値が受け入れられないことを確認するのが不可能な場合 (たとえば、コンパイル時に適切な型チェックを行わない言語の場合)、配列内の `null` 値はそのまま保存されなければなりません (つまり、`null` としてSpanProcessorやExporterに渡されます)。Exporterが `null` 値のエクスポートをサポートしていない場合には、それらの値を 0 や `false` 、あるいは空の文字列で置き換えてもかまいません(MAY)。これは、インデックスが同期している2つの配列として表現されるマップ/辞書構造に必要です(例えば、2つの属性 `header_keys` と `header_values` があり、どちらもマッピング `header_keys[i] -> header_values[i]` を表す文字列の配列を含んでいる場合)。 77 | 78 | 81 | 82 | 命名のガイドラインは、[属性とラベルの命名](attribute-and-label-naming.md)を参照してください。 83 | 84 | -------------------------------------------------------------------------------- /specification/specification/compatibility/openmetrics.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenMetrics 互換性 6 | 7 | 10 | 11 | **Status**: [Experimental](../document-status.md). 12 | 13 | 19 | 20 | OpenTelemetry metricsは、[OpenMetrics](https://openmetrics.io/)仕様との互換性を提供することを目的としています。互換性の拡張と要件については、[Prometheus Working Group](https://github.com/open-telemetry/wg-prometheus/blob/main/specification.md)に記載されています。 21 | -------------------------------------------------------------------------------- /specification/specification/context/context.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # Context 6 | 7 | 10 | 11 | **Status**: [Stable, Feature-freeze](../document-status.md). 12 | 13 | 14 |
目次 15 | 16 | 26 | 27 | - [概要](#概要) 28 | - [キーの作成](#キーの作成) 29 | - [値の取得](#値の取得) 30 | - [値の設定](#値の設定) 31 | - [任意のグローバルな操作](#任意のグローバルな操作) 32 | - [現在のContextを取得](#現在のContextを取得) 33 | - [Contextのアタッチ](#Contextのアタッチ) 34 | - [Contextのデタッチ](#Contextのデタッチ) 35 | 36 | 37 |
38 | 39 | 42 | 43 | ## 概要 44 | 45 | 51 | 52 | `Context`は、APIの境界を越えて、論理的に関連付けられた実行ユニット間で、実行スコープ付きの値を伝達する伝搬メカニズムです。横断的な関心事は、同じ共有された `Context` オブジェクトを使用してプロセス内のデータにアクセスします。 53 | 54 | 59 | 60 | `Context` は不変でなければなりません(MUST)し、Contextへの書き込み操作では、元の値と指定された値が更新された新しい `Context` が作成されなければなりません (MUST)。 61 | 62 | 69 | 70 | 言語は、広く使われている単一の `Context` 実装があれば、それを使うことが期待されます。極めて明確な既存のオプションが利用できない場合には、OpenTelemetryは独自の`Context`実装を提供しなければなりません(MUST)。言語によっては、その使用方法は明示的なものにも暗黙的なものにもなる場合があります。 71 | 72 | 79 | 80 | `Context` を暗黙的に使用する言語で計装を実装するユーザは、`Context` API を直接使用することはお勧めできません。そのような場合には、指定した `Context` に対してTrace エントリやBaggageエントリを設定するなどの操作を行うために、代わりに横断的な関心事のAPI を使用して `Context` を操作することになります。 81 | 82 | 86 | 87 | `Context`には、以下のような操作が想定されており、それぞれの言語で違いがあります: 88 | 89 | 92 | 93 | ## キーの作成 94 | 95 | 101 | 102 | キーは、横断的な関心事がローカルな状態へのアクセスを制御するために使用されます。キーは一意であるため、同じContextを使用する他のライブラリが誤って同じキーを使用することはありません。関係者は、自分のキーへの直接のパブリックアクセスを提供するのではなく、APIを介してデータアクセスを仲介することが推奨されます。 103 | 104 | 107 | 108 | このAPIは、以下のパラメータを受け入れなければなりません(MUST)。 109 | 110 | 113 | 114 | - キーの名前。キー名はデバッグのために存在するもので、キーを一意に識別するものではありません。同じ名前で `CreateKey` を複数回呼び出しても、言語上の制約がない限り、同じ値を返すべきではありません(SHOULD NOT)。言語によって、期待される型の制限が異なる場合があるので、このパラメータは実装上の詳細にとどまります。 115 | 116 | 119 | 120 | このAPIは、新しく作成されたキーを表す不透明なオブジェクトを返さなければなりません(MUST)。 121 | 122 | 125 | 126 | ## 値の取得 127 | 128 | 132 | 133 | 横断的な関心事は、`Context`で表される現在の実行状態に保存されている、自分のローカルな状態にアクセスすることができます。 134 | 135 | 138 | 139 | このAPIは、以下のパラメータを受け入れなければなりません(MUST)。 140 | 141 | 145 | 146 | - `Context` 147 | - キー 148 | 149 | 152 | 153 | このAPI は、指定されたキーの `Context` 内の値を返さなければなりません (MUST)。 154 | 155 | 158 | 159 | ## 値の設定 160 | 161 | 165 | 166 | 横断的な関心事は、`Context`で表される現在の実行状態に、自分のローカルな状態を設定できます。 167 | 168 | 171 | 172 | このAPIは、以下のパラメータを受け入れなければなりません(MUST): 173 | 174 | 179 | 180 | - `Context` 181 | - キー 182 | - 設定する値 183 | 184 | 187 | 188 | このAPI は、新しい値を含む新しい `Context` を返さなければなりません。 189 | 190 | 193 | 194 | ## 任意のグローバルな操作 195 | 196 | 202 | 203 | これらの操作は、`Context` を暗黙のうちに使用する言語によってのみ実装されることが期待されており、したがって任意です。これらの操作は、SDKコンポーネントやOpenTelemetry 計装ライブラリによる自動スコープ切り替えの実装や、高レベルAPIの定義にのみ使用されるべき(SHOULD)です。 204 | 205 | 208 | 209 | ### 現在のContextを取得 210 | 211 | 212 | 215 | 216 | このAPIは、呼び出し元の現在の実行ユニットに関連する`Context`を返さなければなりません(MUST)。 217 | 218 | 221 | 222 | ### Contextのアタッチ 223 | 224 | 227 | 228 | 呼び出し元の現在の実行ユニットに `Context` を関連付けます。 229 | 230 | 233 | 234 | このAPIは、以下のパラメータを受け入れなければなりません(MUST)。 235 | 236 | 239 | 240 | - `Context` 241 | 242 | 246 | 247 | このAPI は、以前の `Context` を復元するための `Token` として使用可能な値を返さなければなりません (MUST)。 248 | 249 | 253 | 254 | 注意点として、この操作を行う際には、必ず[Contextのデタッチ](#Contextのデタッチ)を呼び出す必要があります。 255 | 256 | 259 | 260 | ### Contextのデタッチ 261 | 262 | 266 | 267 | 呼び出し元の現在の実行ユニットに関連付けられた `Context` を、指定された `Context` をアタッチする前の値にリセットします。 268 | 269 | 277 | 278 | この操作は、正しい `Context` が呼び出し元の現在の実行ユニットに関連付けられていることを確認するのに役立つことを目的としています。ユーザーはこの操作を頼りに、間違った呼び出し順序、つまり現在のインスタンスではない `Context` を切り離そうとしているかを調べられます。この場合、この操作は、エラーをログに記録したり、エラー値を返したりして、呼び出し順序が間違っていることをユーザーに警告するシグナルを発することができます。 279 | 280 | 283 | 284 | このAPIは、以下のパラメータを受け入れなければなりません(MUST): 285 | 286 | 289 | 290 | - 以前に `Context` をアタッチした際に返された `Token` 291 | 292 | 296 | 297 | このAPI は、操作が成功したかどうかを確認するために使用する値を返してもかまいません(MAY)。 298 | -------------------------------------------------------------------------------- /specification/specification/document-status.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 文書ステータスの定義 6 | 7 | 13 | 14 | 仕様書(ファイル)は、"ステータス"を明示的に定義することができます。この場合、"ステータス"は個々の文書にのみ適用され、仕様書全体や他の文書には適用されません。以下の表では、ステータスの意味を説明します。 15 | 16 | 19 | 20 | ## ライフサイクル ステータス 21 | 22 | 25 | 26 | サポート保証と許可された変更は、ドキュメントのライフサイクルによって管理されています。 27 | 28 | 36 | 37 | |ステータス |説明| 38 | |-----------------------|-----------| 39 | |明示的な"ステータス"なし|Experimentalと同じ| 40 | |Experimental |破壊的な変更が許可されている| 41 | |Stable |破壊的な変更はできない。詳細は [安定保証](versioning-and-stability.md#stable) を参照してください| 42 | |Deprecated |編集上の変更を除き、変更はできない| 43 | 44 | 47 | 48 | ## フィーチャーフリーズ 49 | 50 | 53 | 54 | 上記のステータスに加えて、文書には `Feature-freeze` というマークが付けられていることがあります。これらの文書は、技術委員会が仕様の他の分野に集中する時間を確保するため、現在は新しい機能要求を受け付けていない、ということを示します。編集上の変更はまだ受け付けています。既存機能の本番時に起きる問題に対処する変更は引き続き受け付けられています。 55 | 56 | 59 | 60 | フィーチャーフリーズはライフサイクルの状態とは別物です。ライフサイクルは文書のサポート要件を表し、フィーチャフリーズは仕様コミュニティの現在取り組んでいる箇所を示すだけです。フィーチャーフリーズラベルは、どのライフサイクル段階でも文書に適用することができます。定義により、deprecatedの文書には、フィーチャフリーズが適用されます。 61 | 62 | 65 | 66 | ## 混合 (`Mixed`) 67 | 68 | 71 | 72 | いくつかの文書には、異なるステータスを持つ個別のセクションがあります。これらの文書は、わかりやすくするために、上部に `Mixed` というステータスでマークされています。 73 | -------------------------------------------------------------------------------- /specification/specification/error-handling.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetryでのエラー処理 6 | 7 | 12 | 13 | OpenTelemetryは、ユーザーがアプリケーションコードを監視するのに役立つテレメトリデータを生成します。ほとんどの場合、ライブラリが実行する作業は、アプリケーション・ビジネス・ロジックの観点からは本質的なものではありません。ユーザーは、ライブラリが計測されたアプリケーションの動作を大幅に変更するよりも、テレメトリデータを失うことを好むと想定しています。 14 | 15 | 20 | 21 | OpenTelemetry は、プラットフォームの拡張メカニズムを介して有効にすることも、実行時に動的にロードすることもできます。これにより、エンドユーザにとってはライブラリの使用が目立たなくなり、アプリケーション開発者の制御外になることさえあります。このため、エラー処理に関していくつかのユニークな要件があります。 22 | 23 | 26 | 27 | ## エラー処理の基本原理 28 | 29 | 32 | 33 | OpenTelemetry の実装は、実行時に未処理の例外を投げてはなりません(MUST NOT)。 34 | 35 | 43 | 44 | 1. APIメソッドは、エンドユーザーが誤って使用した場合に、処理されない例外を投げてはなりません(MUST NOT)。 45 | APIとSDKは、欠落した、または無効な引数に対する安全なデフォルトを提供すべきです(SHOULD)。 46 | 例えば、`Span` の構築時にSpan名の引数に `null` を渡した場合、`empty` のような名前を使用することができます。 47 | 2. API または SDK は、初期化時にアプリケーションを高速で失敗(_fail fast_)させ、アプリケーションを失敗させる可能性があります(例:ユーザー設定や環境が悪いためなど。しかし、アプリケーションが実行時に後で失敗する原因になってはなりません(MUST NOT)) 48 | 3. SDK は、独自の操作でエラーが発生した場合、処理されない例外をスローしてはなりません(MUST NOT)。 49 | 例えば、エクスポーターは、テレメトリデータを送信するエンドポイントに到達できない場合に例外をスローしてはなりません。 50 | 51 | 54 | 55 | ## ガイダンス 56 | 57 | 71 | 72 | 1. 外部コールバックを受け入れるAPIメソッドは、すべてのエラーを処理しなければなりません(MUST)。 73 | 2. バックグラウンドタスク(スレッド、非同期タスク、spawnされたプロセスなど)は、例外がエンドユーザーアプリケーションに影響を与えないように、グローバルエラーハンドラのコンテキストで実行されなければなりません。 74 | 3. 長時間実行中のバックグラウンドタスクは、内部エラーに応答して永続的な失敗を起こしてはいけません。 75 | 一般的に、内部例外は例外の原因となったリクエストの実行コンテキストにのみ影響を与えるべきです。 76 | 4. 内部エラー処理は言語固有の規約に従うべきです。 77 | 一般的に、開発者はエラーハンドラの範囲を最小限にし、予想される例外のために特別な処理を追加すべきです。 78 | 5. 外部のコールバックやオーバーライド可能なインタフェースに注意してください。スローすることを期待してください。 79 | 6. APIやSDKのユーザーが明示的に提供していないメソッドをコールバックとして呼び出すことに注意してください。 80 | SDKがユーザオブジェクト上で呼び出すことにしたメソッド `ToString` は、実装が悪いとスタックオーバーフローを起こす可能性があります。 81 | アプリケーションがこのメソッドを呼び出さないことはよくあることで、この実装の悪さがアプリケーションのオーナーに見つかることはありません。 82 | 7. APIコールが`非null`値であると予想される値を返す場合(処理ロジックに誤りがあった場合)、SDKは事前に(_ideally_)割り当てられていてすぐに利用可能な "no-op"またはその他の "default"オブジェクトを返さなければなりません(MUST)。 83 | これにより、APIコールサイトが `null` オブジェクトのメソッドやプロパティにアクセスしようとしてもクラッシュすることはありません。 84 | 85 | 88 | 89 | ## エラー処理とパフォーマンス 90 | 91 | 95 | 96 | エラー処理と広範な入力の検証は、特にコンパイル時に入力オブジェクトの型が保証されていない動的な言語では、パフォーマンスの低下を引き起こす可能性があります。ランタイムの型チェックはパフォーマンスに影響を与え、エラーが発生しやすく、最善の努力にもかかわらず例外が発生する可能性があります。 97 | 98 | 102 | 103 | 例外がユーザーコードに漏れないことを保証するグローバル例外処理ロジックを持つことが推奨されます。そして、SDKのパフォーマンス、より良いエラー時の動作とSDKエラーのトラブルシューティング方法を提供する型チェックの充実度のトレードオフについて、合理的なバランスを取ってください。 104 | 105 | 108 | 109 | ## 自己診断 110 | 111 | 114 | 115 | すべての OpenTelemetry ライブラリ(API、SDK、エクスポート、計装など)は、自己診断メトリック、Span、およびその他のテレメトリを公開することが推奨されています。 116 | 117 | 121 | 122 | このようなテレメトリの良い例の一つは、エクスポータがテレメトリのアップロードにどれくらいの時間を費やしているかを示す`Span` エクスポータです。もう一つの例は、`SpanProcessor`によって公開されるメトリックで、アップロードされるテレメトリデータの現在のキューサイズを公開しています。 123 | 124 | 128 | 129 | ユーザーに公開されているエラーをライブラリが抑制するときはいつでも、ライブラリは言語固有の規約を使用してエラーをログに記録するべきです(SHOULD)。SDKは、エンドユーザーがアプリケーションコードとは別に自己診断を処理できるように、コールバックを公開しても構いません(MAY)。 130 | 131 | 134 | 135 | ## エラーハンドラの設定 136 | 137 | 143 | 144 | SDK の実装では、関連するエラーに対するライブラリのデフォルトのエラー処理動作をエンドユーザーが変更できるようにしなければなりません(MUST)。アプリケーション開発者は、APIの無効な使用や不正な設定をキャッチするために、ステージング環境で厳格なエラー処理を実行したいと思うかもしれません。この方法でカスタムエラーハンドラを設定することは、上記で概説した基本的なエラー処理の原則に対する唯一の例外であることに注意してください。エンドユーザーがカスタムエラーハンドラを設定または登録するメカニズムは、言語固有の規約に従うべきです。 145 | 146 | 149 | 150 | ### 例 151 | 152 | 157 | 158 | これらは、エンドユーザーがカスタム・エラー・ハンドラを登録する方法の例です。例は説明のみを目的としています。OpenTelemetryクライアントの作成者は、そのデザインが上記の要件に合致していれば、これらの例から自由に逸脱できます。 159 | 160 | 161 | #### Go 162 | 163 | ```go 164 | // 基本的なエラー処理のインターフェース 165 | type ErrorHandler interface { 166 | Handle(err error) 167 | } 168 | 169 | func Handler() ErrorHandler 170 | func SetHandler(handler ErrorHandler) 171 | ``` 172 | 173 | ```go 174 | // カスタムエラーハンドラーを登録 175 | type IgnoreExporterErrorsHandler struct{} 176 | 177 | func (IgnoreExporterErrorsHandler) Handle(err error) { 178 | switch err.(type) { 179 | case *SpanExporterError: 180 | default: 181 | fmt.Println(err) 182 | } 183 | } 184 | 185 | func main() { 186 | // 他の設定… 187 | opentelemetrysdk.SetHandler(IgnoreExporterErrorsHandler{}) 188 | } 189 | 190 | ``` 191 | 192 | ##### Java 193 | 194 | 198 | 199 | OpenTelemetry Javaは、[java.util.logging](https://docs.oracle.com/javase/7/docs/api/java/util/logging/package-summary.html)を使用して、エラーを含むすべてのログを出力し、処理します。カスタムハンドラやフィルタは、コード内でも、Javaのロギング設定ファイルを使っても登録することができます。 200 | 201 | 202 | ```properties 203 | ## すべてのエラーログを出力しない 204 | io.opentelemetry.level = OFF 205 | ``` 206 | 207 | ```java 208 | // エクスポーターから来たエラーをログ出力しないようにするカスタムフィルターを作成 209 | public class IgnoreExportErrorsFilter implements Filter { 210 | 211 | public boolean isLoggable(LogRecord record) { 212 | return !record.getMessage().contains("Exception thrown by the export"); 213 | } 214 | } 215 | ``` 216 | 217 | ```properties 218 | ## カスタムフィルターをBatchSpanProcessorに登録 219 | io.opentelemetry.sdk.trace.export.BatchSpanProcessor = io.opentelemetry.extensions.logging.IgnoreExportErrorsFilter 220 | ``` -------------------------------------------------------------------------------- /specification/specification/library-layout.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetryプロジェクトのパッケージレイアウト 6 | 7 | 12 | 13 | このドキュメントは、OpenTelemetryプロジェクトの基本的なレイアウトの「ルック＆フィール」を文書化したものです。このパッケージレイアウトは意図的に一般的なものになっており、言語固有のパッケージ構造を押し付けようとはしていません。 14 | 15 | 18 | 19 | ## API パッケージ 20 | 21 | 24 | 25 | ここでは、OpenTelemetry APIパッケージの一般的なパッケージ構造を提案します。 26 | 27 | 30 | 31 | 典型的なトップレベルディレクトリのレイアウト: 32 | 33 | 47 | 48 | ``` 49 | api 50 | ├── context 51 | │ └── propagation 52 | ├── metrics 53 | ├── trace 54 | │ └── propagation 55 | ├── baggage 56 | │ └── propagation 57 | ├── internal 58 | └── logs 59 | ``` 60 | 61 | 64 | 65 | > 小文字、CamelCase、Snake Case(snake_caseとしてスタイリング)の名前の使用は、言語によって異なります。 66 | 67 | 70 | 71 | ### `/context` 72 | 73 | 76 | 77 | このディレクトリでは、プロセス中のコンテキスト伝播を提供するAPIについて説明します。 78 | 79 | 82 | 83 | ### [/metrics](./metrics/api.md) 84 | 85 | 88 | 89 | このディレクトリでは、アプリケーション・メトリックを記録するために使用できるMetrics APIについて説明しています。 90 | 91 | 94 | 95 | ### [/baggage](baggage/api.md) 96 | 97 | 101 | 102 | このディレクトリでは、コンテキストプロパゲーションやMetrics関連のラベリングを管理するために使用できるBaggage APIについて説明しています。 103 | 104 | 107 | 108 | ### [/trace](trace/api.md) 109 | 110 | 113 | 114 | このAPIは、いくつかの主要なクラスで構成されています。 115 | 116 | 121 | 122 | - すべての操作には `Tracer` が使われます。[Tracer](trace/api.md#tracer)のセクションを参照してください。 123 | - `Span` は、現在のオペレーション実行に関する情報を格納する可変(mutable)オブジェクトです。[Span](trace/api.md#span)のセクションを参照してください。 124 | 125 | 128 | 129 | ### `/internal` (_任意_) 130 | 131 | 136 | 137 | ユーザーに公開されるべきではないライブラリのコンポーネントや実装。言語によって内部コンポーネントの慣習的なレイアウトが決まっている場合は、その言語の慣習的なスタイルに従ってください。 138 | 139 | 142 | 143 | ### `/logs` (_将来的に_) 144 | 145 | 148 | 149 | > TODO: ログ操作 150 | 151 | 154 | 155 | ## SDK パッケージ 156 | 157 | 160 | 161 | ここでは、OpenTelemetry SDKパッケージの一般的なパッケージ構造を提案します。 162 | 163 | 166 | 167 | 典型的なトップレベルディレクトリのレイアウト: 168 | 169 | 181 | 182 | ``` 183 | sdk 184 | ├── context 185 | ├── metrics 186 | ├── resource 187 | ├── trace 188 | ├── baggage 189 | ├── internal 190 | └── logs 191 | ``` 192 | 193 | 196 | 197 | > 小文字、CamelCase、Snake Case(snake_caseとしてスタイリング)の名前の使用は、言語によって異なります。 198 | 199 | 202 | 203 | ### `/sdk/context` 204 | 205 | 208 | 209 | api/contextのSDK実装について説明しているディレクトリです。 210 | 211 | 214 | 215 | ### `/sdk/metrics` 216 | 217 | 220 | 221 | api/metricsのSDK実装について説明しているディレクトリです。 222 | 223 | 226 | 227 | ### [/sdk/resource](resource/sdk.md) 228 | 229 | 235 | 236 | リソースディレクトリでは主に、統計やTraceが記録されるエンティティに関する情報をキャプチャする[リソース](overview.md#resources)というタイプが定義されています。例えば、Kubernetesコンテナが公開するメトリックは、クラスタ、名前空間、ポッド、コンテナ名を指定するリソースにリンクできます。 237 | 238 | 241 | 242 | ### `/sdk/baggage` 243 | 244 | 247 | 248 | ### [/sdk/trace](trace/sdk.md) 249 | 250 | 253 | 254 | api/traceのSDK実装について説明しているディレクトリです。 255 | 256 | 259 | 260 | ### `/sdk/internal` (_任意_) 261 | 262 | 267 | 268 | ユーザーに公開されるべきではないライブラリのコンポーネントや実装。言語によって内部コンポーネントの慣習的レイアウトが決まっている場合は、その言語の慣習的スタイルに従ってください。 269 | 270 | 273 | 274 | ### `/sdk/logs` (_将来的に_) 275 | 276 | 279 | 280 | > TODO: ログ操作 281 | 282 | -------------------------------------------------------------------------------- /specification/specification/logs/img/app-to-file-logs-fb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/app-to-file-logs-fb.png -------------------------------------------------------------------------------- /specification/specification/logs/img/app-to-file-logs-otelcol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/app-to-file-logs-otelcol.png -------------------------------------------------------------------------------- /specification/specification/logs/img/app-to-otelcol.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/app-to-otelcol.png -------------------------------------------------------------------------------- /specification/specification/logs/img/application-api-sdk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/application-api-sdk.png -------------------------------------------------------------------------------- /specification/specification/logs/img/separate-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/separate-collection.png -------------------------------------------------------------------------------- /specification/specification/logs/img/unified-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/logs/img/unified-collection.png -------------------------------------------------------------------------------- /specification/specification/metrics/README.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry Metrics 6 | 7 | **Status**: [Experimental](../document-status.md) 8 | 9 | **Owner:** 10 | 11 | * [Reiley Yang](https://github.com/reyang) 12 | 13 | **Domain Experts:** 14 | 15 | * [Bogdan Brutu](https://github.com/bogdandrutu) 16 | * [Josh Suereth](https://github.com/jsuereth) 17 | * [Joshua MacDonald](https://github.com/jmacd) 18 | 19 | 25 | 26 | 注意:この仕様は大きく変更される可能性があります。言語クライアントのメンテナに負担をかけないように、[OTEP](https://github.com/open-telemetry/oteps#opentelemetry-enhancement-proposal-otep)で明示的に伝えられない限り、OpenTelemetryのクライアントが実装を開始することは推奨しません。 27 | 28 |
29 | 30 | Table of Contents 31 | 32 | 33 | 45 | 46 | * [概要](#概要) 47 | * [デザインゴール](#デザインゴール) 48 | * [コンセプト](#コンセプト) 49 | * [API](#api) 50 | * [SDK](#sdk) 51 | * [仕様](#仕様) 52 | * [Metrics API](./api.md) 53 | * Metrics SDK (未定義) 54 | * [Metrics データモデルとプロトコル](datamodel.md) 55 | * [セマンティック規約](./semantic_conventions/README.md) 56 | 57 |
58 | 59 | 62 | 63 | ## 概要 64 | 65 | 68 | 69 | ### デザインゴール 70 | 71 | 75 | 76 | 現在、多くの確立されたメトリック・ソリューションが存在することを考えると、OpenTelemetryのメトリックの取り組みの目標を理解することは重要です。 77 | 78 | 86 | 87 | * **メトリックを他のシグナルに結びつけることができること**。例えば、メトリックとトレースはExamplarを介して相関させることができ、メトリックのディメンションは[Baggage](../baggage/api.md)や[Context](../context/context.md)を介して情報を追加させることができます。さらに、[Resource](../resource/sdk.md)は、[logs](../overview.md#log-signal)/[metrics](../overview.md#metric-signal)/[traces](../overview.md#tracing-signal)に一貫した方法で適用することができます。 88 | 89 | 95 | 96 | * **[OpenCensus](https://opencensus.io/)のユーザーがOpenTelemetryに移行するための道筋を提供すること**。これはOpenTelemetryの当初の目標であった、OpenCensusとOpenTracingの収束です。私たちは、APIの1-1マッピングを行うのではなく、セマンティクスと機能を提供することに注力します。 97 | 98 | 107 | 108 | * **既存のメトリック計測プロトコルや標準規格との連携**。最低限の目標は、[Prometheus](https://prometheus.io/)と[StatsD](https://github.com/statsd/statsd)を完全にサポートすることです。ユーザーは、OpenTelemetryクライアントと[Collector](../overview.md#collector)を使ってメトリックを収集し、エクスポートすることができ、ネイティブクライアントと同じ機能を実現することができます。 109 | 110 | 113 | 114 | ### コンセプト 115 | 116 | 119 | 120 | #### API 121 | 122 | 125 | 126 | **OpenTelemetry Metrics API**(以下、「API」)は、2つの目的を持っています。 127 | 128 | 133 | 134 | * 生の測定値を効率的かつ同時に取得する。 135 | * 計測器と[SDK](#sdk)を切り離し、アプリケーションでSDKを指定/インクルードすることが可能。 136 | 137 | 144 | 145 | アプリケーションに[SDK](#sdk)が明示的に含まれていない/有効になっていない場合、テレメトリデータは収集されません。詳細については、全体的な[OpenTelemetry API](../overview.md#api)のコンセプトと、[APIと最小実装](../library-guidelines.md#APIと最小実装)を参照してください。 146 | 147 | 150 | 151 | #### SDK 152 | 153 | 158 | 159 | **OpenTelemetry Metrics SDK**(以下、SDK)は、APIを実装し、設定、集約、プロセッサー、エクスポーターなどの機能と拡張性を提供します。 160 | 161 | 167 | 168 | OpenTelemetryでは、実行時に異なるSDKを設定できるように、[SDKからAPIの分離](../library-guidelines.md#requirements)を要求しています。詳細については、全体的な[OpenTelemetry SDK](../overview.md#sdk)のコンセプト概念をご参照ください。 169 | 170 | 173 | 174 | #### プログラミングモデル 175 | 176 | Processor +--> Aggregator +--> Exporter +--> Another process 183 | | Meter B | | | | | | | 184 | | Instrument Z | +-----------+ +------------+ +----------+ 185 | | ... | 186 | | ... | 187 | +------------------+ 188 | ``` 189 | --> 190 | 191 | ```text 192 | +------------------+ 193 | | MeterProvider | 194 | | Meter A | +-----------+ +------------+ +----------+ 195 | | Instrument X | Measurements... | | | | | | 196 | | Instrument Y +-----------------> Processor +--> Aggregator +--> Exporter +--> Another process 197 | | Meter B | | | | | | | 198 | | Instrument Z | +-----------+ +------------+ +----------+ 199 | | ... | 200 | | ... | 201 | +------------------+ 202 | ``` 203 | 204 | 207 | 208 | ## 仕様 209 | 210 | 216 | 217 | * [Metrics API](./api.md) 218 | * Metrics SDK (未定義) 219 | * [Metrics データモデルとプロトコル](datamodel.md) 220 | * [セマンティック規約](./semantic_conventions/README.md) 221 | 222 | 225 | 226 | ## 参照 227 | 228 | 231 | 232 | * メトリックAPI/SDKプロトタイピングのためのシナリオ ([OTEP 146](https://github.com/open-telemetry/oteps/blob/main/text/metrics/0146-metrics-prototype-scenarios.md)) 233 | 234 | -------------------------------------------------------------------------------- /specification/specification/metrics/img/accumulator-detail.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/accumulator-detail.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/metrics-sdk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/metrics-sdk.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/model-cumulative-sum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/model-cumulative-sum.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/model-delta-sum.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/model-delta-sum.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/model-event-layer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/model-event-layer.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/model-layers-stream.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/model-layers-stream.png -------------------------------------------------------------------------------- /specification/specification/metrics/img/model-layers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/metrics/img/model-layers.png -------------------------------------------------------------------------------- /specification/specification/metrics/semantic_conventions/openmetrics-guidelines.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenMetricsとの相互運用のためのガイダンス 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | 13 | 14 | **このドキュメントは現在進行中であり、OpenMetricsの仕様がさらに発展するにつれて更新される予定です。 15 | 16 | 19 | 20 | ## 概要 21 | 22 | 26 | 27 | OpenTelemetryは、2つの方法でOpenMetricsまたはPrometheusエクスポートフォーマットを使用するシステムと相互運用する必要があります。 28 | 29 | 36 | 37 | * OpenTelemetryは、OpenMetrics形式で表現されたメトリックを受け入れて伝播させ、下流のシステム(OpenTelemetry Collector、zPages、ベンダーのバックエンドなど)にエクスポートする必要があるかもしれません。 38 | * OpenTelemetryでは、OpenTelemetryで生成したメトリックをOpenMetricsの公開フォーマットで公開する必要があるかもしれません。 39 | 40 | 43 | 44 | ### OpenMetrics から OpenTelemetry へ 45 | 46 | 51 | 52 | OpenTelemetryコレクターは、Prometheusレシーバーを実装しており、OpenMetricsエクスポートフォーマットのメトリックを読み取ります。詳細については、[Prometheus Receiver Design Document](https://github.com/open-telemetry/opentelemetry-collector/blob/master/receiver/prometheusreceiver/DESIGN.md)を参照してください。 53 | 54 | 57 | 58 | ### OpenTelemetry から OpenMetrics へ 59 | 60 | 63 | 64 | #### Name と Label キー 65 | 66 | 71 | 72 | OpenTelemetryのメトリックをOpenMetricsフォーマットで公開することは、主にメトリックとラベルの命名に関して問題があります。OpenMetricsの公開フォーマットでは、OpenTelemetryで許可されているいくつかの文字が明示的に禁止されています。 73 | 74 | 79 | 80 | OpenTelemetryのメトリックイベントをOpenMetricsの公開フォーマットに変換する際には、nameフィールドおよびすべてのラベルキーを、文字または数字ではないすべての文字をアンダースコアに置き換えることでサニタイズしなければなりません(MUST)。 81 | 82 | 85 | 86 | 疑似コードの例: 87 | 88 | 94 | 95 | ```ruby 96 | def sanitize(name) 97 | return name.sub(/\W/, '_') 98 | ``` 99 | 100 | 104 | 105 | Prometheusデータモデル・ドキュメントの[Metric名とラベル](https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels)も参照してください。 106 | 107 | 112 | 113 | OpenMetricsでは、メトリック名が数字で始まることを認めていません。OpenTelemetryの[instrument naming requirements](../api.md#instrument-naming-requirements)でも、Metric instrumentsの最初の文字が数字でないことを要求しています。 114 | 115 | 120 | 121 | 本仕様に準拠しないメトリックイベントがOpenTelemetryで生成された場合、結果として得られるOpenMetricsメトリックの名前の前にアンダースコアを付けても構いません(MAY)。 122 | 123 | -------------------------------------------------------------------------------- /specification/specification/metrics/semantic_conventions/process-metrics.md: -------------------------------------------------------------------------------- 1 | # OSプロセスメトリックのセマンティック規約 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | 15 | 16 | この文書では、OpenTelemetryの一般的なOSプロセス・レベル・メトリックのInstrumentsとラベルについて説明しています。また、このドキュメントで明示的に定義されていないInstrumentsを作成する際には、[一般的なmetricセマンティック規約](README.md#general-metric-semantic-conventions)を考慮してください。OSプロセス・メトリックは、プログラムの実行時環境とは関係なく、OSから測定値を取得する必要があります。ランタイム環境メトリックについては、[ランタイム環境メトリックのセマンティック規約](runtime-environment-metrics.md)を参照してください。 17 | 18 | 19 | 20 | 21 | 22 | 23 | - [Metric Instruments](#metric-instruments) 24 | 25 | 26 | 27 | ## Metric Instruments 28 | 29 | TODO 30 | -------------------------------------------------------------------------------- /specification/specification/metrics/semantic_conventions/rpc.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 一般的なRPCの規約 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | 15 | 16 | このセクションで説明する規約は、RPC固有のものです。RPC操作が発生すると、その操作に関するメトリック・イベントが生成・報告され、その操作についての情報が提供されます。メトリック・イベントにRPCラベルを追加することで、きめ細かなフィルタリングが可能になります。 17 | 18 | 19 | 20 | 21 | 22 | 30 | 31 | - [Metric instruments](#metric-instruments) 32 | * [RPC Server](#rpc-server) 33 | * [RPC Client](#rpc-client) 34 | - [Labels](#labels) 35 | * [Service name](#service-name) 36 | - [gRPC規約](#grpc規約) 37 | 38 | 39 | 40 | 43 | 44 | ## Metric instruments 45 | 46 | 50 | 51 | RPC操作の記述には、以下のInstrumentsを使用しなければなりません(MUST)。これらは、指定されたタイプと単位でなければなりません(MUST)。 52 | 53 | 56 | 57 | *注:RPCサーバとクライアントのメトリックが分割され、クライアント/サーバの境界を越えた相関が可能になります。例えば、RPCメソッドのレイテンシーを並べて、クライアントが見ているレイテンシーの原因がサーバーにあるかどうかを判断できます。* 58 | 59 | 62 | 63 | ### RPC Server 64 | 65 | 68 | 69 | 以下は、RPCサーバーのInstrumentsの表です。 70 | 71 | 80 | 81 | | Name | Instrument | 単位 | 説明 | Status | Streaming | 82 | |----------------------------|---------------|--------------|-------------|--------|-----------| 83 | | `rpc.server.duration` | ValueRecorder | milliseconds | インバウンドRPCの継続期間 | Recommended | 該当なし。 ストリーミングRPCでは、この指標をバッチ開始からバッチ終了までとして記録することがありますが、実際には解釈が困難です | 84 | | `rpc.server.request.size` | ValueRecorder | bytes | RPCリクエストメッセージのサイズ(無圧縮) | Optional | ストリーミングバッチでメッセージごとに記録 | 85 | | `rpc.server.response.size` | ValueRecorder | bytes | RPCレスポンスメッセージのサイズ(無圧縮) | Optional | ストリーミングバッチで応答ごとに記録 | 86 | | `rpc.server.requests_per_rpc` | ValueRecorder | count | RPCごとに受信したメッセージの数。 ストリーミングを行わないRPCでは1とします。 | Optional | Required | 87 | | `rpc.server.responses_per_rpc` | ValueRecorder | count | RPCごとに送信したメッセージの数。 ストリーミングを行わないRPCでは1とします。 | Optional | Required | 88 | 89 | 92 | 93 | ### RPC Client 94 | 95 | 99 | 100 | 以下は、RPCクライアントのInstrumentsの表です。 これらは、ストリーミングRPCではなく、従来のRPCの使用に適用されます。 101 | 102 | 111 | 112 | | Name | Instrument | 単位 | 説明 | Status | Streaming | 113 | |----------------------------|---------------|--------------|-------------|--------|-----------| 114 | | `rpc.client.duration` | ValueRecorder | milliseconds | アウトバウンドRPCの継続時間 | Recommended | 該当なし。 ストリーミングRPCでは、この指標をバッチ開始からバッチ終了までとして記録することがありますが、実際には解釈が困難です | 115 | | `rpc.client.request.size` | ValueRecorder | bytes | RPCリクエストメッセージのサイズ(無圧縮) | Optional | ストリーミングバッチでメッセージごとに記録 | 116 | | `rpc.client.response.size` | ValueRecorder | bytes | RPCレスポンスメッセージのサイズ(無圧縮) | Optional | ストリーミングバッチで応答ごとに記録 | 117 | | `rpc.client.requests_per_rpc` | ValueRecorder | count | RPCごとに受信したメッセージの数。 ストリーミングを行わないRPCでは1とします。 | Optional | Required | 118 | | `rpc.client.responses_per_rpc` | ValueRecorder | count | RPCごとに送信したメッセージの数。 ストリーミングを行わないRPCでは1とします。 | Optional | Required | 119 | 120 | 123 | 124 | ## Labels 125 | 126 | 130 | 131 | 以下は、メトリックイベントに含めるべきラベルと、そのラベルをサーバー、クライアント、またはその両方に付けるべきかどうかの表です。 132 | 133 | 134 | | Attribute | Type | Description | Examples | Required | 135 | |---|---|---|---|---| 136 | | [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | リモーションシステムを識別する文字列 | `grpc`; `java_rmi`; `wcf` | Yes | 137 | | [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | 呼び出されるサービスのフルネーム(該当する場合は、パッケージ名も含む) | `myservice.EchoService` | いいえ、しかし推奨です | 138 | | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | 呼び出されるメソッドの名前は、Span名の$method部分と等しくなければなりません。 | `exampleMethod` | いいえ、しかし推奨です | 139 | | [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | 相手のリモートアドレス(IPv4ではドット10進数、IPv6では[RFC5952](https://tools.ietf.org/html/rfc5952) | `127.0.0.1` | See below | 140 | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | リモートのホスト名あるいは類似の文字列。下記注釈参照 | `example.com` | See below | 141 | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | リモートのポート番号 | `80`; `8080`; `443` | 下記参照 | 142 | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. 下記注釈参照。 | `ip_tcp` | 下記参照 | 143 | 144 | **Additional attribute requirements:** At least one of the following sets of attributes is required: 145 | 146 | * [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) 147 | * [`net.peer.name`](../../trace/semantic_conventions/span-general.md) 148 | 149 | 150 | 155 | 156 | カーディナリティが高くなるのを避けるために、実装では、想定されるデプロイメントプロファイルに応じて、`net.peer.name`または`net.peer.ip`のうち、最も安定したものを選択する必要があります。 多くのクラウドアプリケーションでは、おそらく `net.peer.name` でしょう。これは、異なる `ip` を持つサーバーが再起動されても、名前を再利用できるからです。 157 | 158 | 163 | 164 | クライアントサイドメトリックでは、接続がIPベースでポートが利用可能な場合、`net.peer.port`が必須となります(クライアントが接続しているサーバーのポートが記述されます)。サーバー側のSpanでは、`net.peer.port`はオプションです(クライアントが接続しているポートが記述されています)。さらに、名前付きパイプバインディングのような非IP接続の場合は、[net.transport][]の設定が必要です。 165 | 166 | 169 | 170 | ### Service name 171 | 172 | 176 | 177 | RPCを受信して処理するサーバプロセスでは、`rpc.service`で提供されるサービス名は必ずしも[`service.name`][]リソース属性と一致する必要はありません。1つのプロセスが複数のRPCエンドポイントを公開することで、複数のRPCサービス名を持つことができます。デプロイメントの観点からは、リソース属性の `service.*` で表されるように、1つの `service.name` を持つ1つのデプロイされたサービスとして扱われます。 178 | 179 | 182 | 183 | [`service.name`]: ../../resource/semantic_conventions/README.md#service 184 | 185 | 188 | 189 | ## gRPC規約 190 | 191 | 194 | 195 | [gRPC][]によるリモート・プロシージャ・コールでは、追加の規約がこのセクションに記載されています。 196 | 197 | 200 | 201 | `rpc.system` には `"grpc"` を設定しなければなりません(MUST)。 202 | 203 | 206 | 207 | [gRPC]: https://grpc.io/ 208 | 209 | -------------------------------------------------------------------------------- /specification/specification/metrics/semantic_conventions/runtime-environment-metrics.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 実行環境メトリックのセマンティック規約 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | 16 | 17 | このドキュメントには、OpenTelemetryにおけるランタイム環境レベルのメトリックのセマンティック規約が含まれています。また、ランタイム環境を計装する際には、[一般的なメトリック](README.md#general-metric-semantic-conventions)、[システム・メトリック](system-metric.md)、[OSプロセス・メトリック](process-metric.md)のセマンティック規約も考慮してください。 18 | 19 | 20 | 21 | 22 | 23 | 27 | 28 | - [Metric計装](#Metric計装) 29 | * [ランタイム環境固有のMetrics - `runtime.{environment}.`](#ランタイム環境固有のMetrics---runtimeenvironment) 30 | 31 | 32 | 33 | 36 | 37 | ## Metric計装 38 | 39 | 48 | 49 | ランタイム環境は、その用語、実装、および特定の指標に対する相対的な値が大きく異なります。例えば、GoとPythonはどちらもガベージコレクション言語ですが、GoランタイムとCPythonランタイムの間でヒープ使用量を直接比較することは意味がありません。このような理由から、本ドキュメントでは、標準的なトップレベルのランタイムメトリック機器を提案しません。追加の議論については[OTEP 108](https://github.com/open-telemetry/oteps/pull/108/files)を参照してください。 50 | 51 | 54 | 55 | ### ランタイム環境固有のMetrics - `runtime.{environment}.` 56 | 57 | 65 | 66 | 特定のランタイム環境に特化したメトリックは、プレフィックスとして `runtime.{environment}.` を付け、[一般的なMetricセマンティック規約](README.md#general-metric-semantic-conventions)に概説されているセマンティック規約に従います。ランタイム計装の作者は、メトリックの名前や値を解釈する際の曖昧さを避けるために、`{environment}`の選択に責任を負います。 67 | 68 | 75 | 76 | 例えば、プログラミング言語の中には、[多くの実装を持つPython](https://wiki.python.org/moin/PythonImplementations)のように、実装が大きく異なる複数の実行環境を持つものがあります。このような言語では、`runtime.cpython.`や`runtime.pypy.`のように、曖昧さを避けるために特定の`{environment}`接頭辞を使用することを検討してください。 77 | 78 | 82 | 83 | 例えば、pthreadとグリーンスレッドの実装など、あるランタイム環境の中でも別の次元を考慮する必要があります。 84 | 85 | -------------------------------------------------------------------------------- /specification/specification/performance-benchmark.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry APIのパフォーマンス・ベンチマーク 6 | 7 | 11 | 12 | このドキュメントでは、OpenTelemetry SDKのパフォーマンスをどのように測定・報告するかについて、一般的なパフォーマンスベンチマークのガイドラインを説明しています。 13 | 14 | 19 | 20 | このベンチマークの目的は、ターゲットプラットフォーム上で与えられたイベントのスループットに対するOpenTelemetry SDKの基本的なパフォーマンスオーバーヘッドを得るためのツールを提供することです。 21 | 22 | 25 | 26 | ## ベンチマークの設定 27 | 28 | 31 | 32 | ### Span設定 33 | 34 | 48 | 49 | - 親の `Span` や親の `SpanContext` は含まないこと。 50 | - デフォルトのSpanは[Kind](./trace/api.md#spankind)と[Status](./trace/api.md#set-status)とすること。 51 | - 属性 `service.name`, `service.version` と各属性に10文字の文字列値、属性 `service.instance.id` にはユニークなUUIDが設定されている [resource](overview.md#resources) に関連付けること。詳細は[Service](./resource/semantic_conventions/README.md#service)を参照してください。 52 | - 1 [attribute](./common/common.md#attributes)には、64ビットの符号付き整数値を指定すること。 53 | - 1 [event](./trace/api.md#add-events)には属性を含まないこと。 54 | - Samplerの`AlwaysOn`を有効にすること。 55 | - 各 `Span` は作成され、すぐに終了すること。 56 | 57 | 60 | 61 | ### Measurement 設定 62 | 63 | 68 | 69 | JITコンパイルのようなブートストラップコストを持つ言語では、測定の前に、同じ`Span`[設定](#span設定)の下で実行されるウォームアップフェーズを行うことが推奨されています。 70 | 71 | 74 | 75 | ## スループット測定 76 | 77 | 80 | 81 | ### Spanの作成 82 | 83 | 89 | 90 | 1秒でOTLP Exporterを使って作成・エクスポートできたSpanの数を、論理コアごとと全論理コアの平均数で表した数値。各Spanには10個の属性が含まれ、各属性には2つの20文字の文字列(1つは属性名、もう1つは値)を含めます。 91 | 92 | 95 | 96 | ## 計装コスト 97 | 98 | 101 | 102 | ### CPU利用率測定 103 | 104 | 116 | 117 | ユーザーによって指定された任意のSpan・スループット数、またはユーザーが数を入力しない場合はデフォルトとして毎秒10,000のSpanを使用して、OTLP Exporterと共にデフォルトで構成されたシンプルなSpan・プロセッサーとバッチ・Span・プロセッサーの両方を備えたSDKのCPU使用率を測定し、報告します。ベンチマークは、エクスポートするターゲット上でListenするout-of-processのOTLPレシーバーを作成するか、out-of-processで実行され、直ちに成功ステータスで応答し、データをドロップする既存のOTLPエクスポーターを採用する必要があります。コレクタは、測定に大きなCPUオーバーヘッドを加えるべきではありません。ベンチマークにはユーザーの処理ロジックが含まれていないため、ベンチマークプログラムの総CPU消費量は、SDKのCPU消費量の近似値とみなすことができます。 118 | 119 | 123 | 124 | 1回のテストの繰り返しにかかる総実行時間は、少なくとも15秒であることが推奨されます。また、平均およびピーク時のCPU使用率を報告する必要があります。 125 | 126 | 129 | 130 | ### メモリ利用率測定 131 | 132 | 136 | 137 | 上記の「CPU使用率」と同じシナリオで、15秒間の動的メモリ消費量(ヒープなど)を測定します。 138 | 139 | 142 | 143 | ## 報告 144 | 145 | 148 | 149 | ### 報告形式 150 | 151 | 155 | 156 | 上記の数値はすべて複数回(最低でも10回を推奨)測定し、報告する必要があります。 157 | -------------------------------------------------------------------------------- /specification/specification/performance.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry APIのパフォーマンスとブロッキング 6 | 7 | 10 | 11 | このドキュメントは、設計者が安全に使用できるOpenTelemetryクライアントを作成するのに役立つ共通原則を定義しています。 12 | 13 | 16 | 17 | ## 主要な原則 18 | 19 | 22 | 23 | ここで、主要な原則を紹介します: 24 | 25 | 29 | 30 | - **ライブラリーがエンドユーザーのアプリケーションをデフォルトでブロックしないこと** 31 | - **ライブラリが制限のないメモリリソースを消費しないこと** 32 | 33 | 36 | 37 | モニタリングを実現するためにはオーバーヘッドが避けられませんが、APIは可能な限りエンドユーザー・アプリケーションを劣化させないようにすべきです。そのため、エンドユーザー・アプリケーションをブロックしたり、メモリ・リソースを過剰に消費したりしてはいけません。 38 | 39 | 42 | 43 | 実装が同時実行をサポートしている場合は、[並行処理とスレッドセーフ](library-guidelines.md#concurrency-and-thread-safety)も参照してください。 44 | 45 | 48 | 49 | ### ノンブロッキングとメモリ消費のトレードオフ 50 | 51 | 54 | 55 | 不完全な非同期I/Oタスクやバックグラウンドタスクは、その状態を維持するためにメモリを消費することがあります。このような場合、メモリ不足を防ぐために一部のタスクを削除することと、情報損失を防ぐためにすべてのタスクを保持することはトレードオフの関係にあります。 56 | 57 | 60 | 61 | OpenTelemetryクライアントにそのようなトレードオフがある場合、エンドユーザーに次のようなオプションを提供する必要があります。 62 | 63 | 70 | 71 | - **情報を損失しない**: すべての情報を保持するが、多くのリソースを消費する可能性がある。 72 | - **ブロッキングしない**: 負荷が大きい場合一部の情報を消失させ、情報消失の開始時と回復時に警告ログを表示する。 73 | - ドロッピングの閾値を変更するオプションを提供すべき 74 | - 効果的なサンプリング比率を示す指標を提供するとよい 75 | - OpenTelemetryクライアントは、ロギングのためにこのオプションを提供するかもしれません 76 | 77 | 80 | 81 | ### エンドユーザーのアプリケーションは、ログのサイズに注意する必要がある 82 | 83 | 86 | 87 | エンドユーザーのアプリケーションがあまりにも多くのログを発する場合、ログはデフォルトで多くのメモリを消費する可能性があります。このデフォルトの動作は、ログを落とすのではなく保存することを目的としています。リソースの使用量を制限するために、エンドユーザーはエクスポート先に渡されるログを減らすことを検討する必要があります。 88 | 89 | 92 | 93 | したがって、OpenTelemetryクライアントは、OpenTelemetryでキャプチャするログをフィルタリングする方法を提供する必要があります。エンドユーザーのアプリケーションは、ログファイルや標準出力(あるいは他の場所)に多くのログを記録したいが、OpenTelemetry エクスポーターにすべてのログを送りたくないという場合があります。 94 | 95 | 98 | 99 | OpenTelemetryクライアントのドキュメントでは、デフォルトではログが多すぎて多くのリソースを消費することを指摘した上で、ログをフィルタリングする方法を案内するのがよいでしょう。 100 | 101 | 104 | 105 | ### シャットダウンと明示的なフラッシュにより、ブロックを可能とする 106 | 107 | 110 | 111 | OpenTelemetryクライアントは、シャットダウン時にエンドユーザーのアプリケーションをブロックする可能性があります。シャットダウン時には、情報の損失を防ぐためにデータをフラッシュしなければなりません。OpenTelemetryクライアントは、シャットダウン時にブロックする場合、ユーザーが設定できるタイムアウトをサポートする必要があります。 112 | 113 | 116 | 117 | OpenTelemetryクライアントが明示的なフラッシュ操作をサポートしていれば、ブロックすることも可能です。しかし、設定可能なタイムアウトをサポートする必要があります。 118 | 119 | 122 | 123 | ## ドキュメンテーション 124 | 125 | 128 | 129 | 言語固有の実装で、本文書に記載されていない特別な特性がある場合は、その特性を文書化する必要があります。 130 | -------------------------------------------------------------------------------- /specification/specification/protocol/README.md: -------------------------------------------------------------------------------- 1 | # OpenTelemetry プロトコル 2 | 3 | これは、新しいOpenTelemetryプロトコル(OTLP)の仕様です。 4 | 5 | - [デザインゴール](design-goals.md) 6 | - [要件](requirements.md) 7 | - [使用](otlp.md) 8 | - [SDK Exporter](exporter.md) 9 | -------------------------------------------------------------------------------- /specification/specification/protocol/design-goals.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry Wireプロトコルのデザインゴール 6 | 7 | 10 | 11 | 以下のような特徴を持つテレメトリデータ交換プロトコルを設計したいと考えています。 12 | 13 | 16 | 17 | - 以下のすべてのタイプのノードでの使用に適していること: 計装されたアプリケーション、テレメトリ・バックエンド、ローカル・エージェント、スタンドアローン・コレクター/フォワーダーなど。 18 | 19 | 22 | 23 | - データ配信の信頼性が高く、データが配信されない場合も明確にわかること。 24 | 25 | 28 | 29 | - シリアライズとデシリアライズのCPU使用率が低いこと。 30 | 31 | 34 | 35 | - パススルーシナリオを含めて、メモリマネージャへの負荷を最小限に抑えること。デシリアライズされたデータが短命で、直後にそのままシリアライズする必要がある場合や、そのような短命のデータが高頻度で作成・破棄される場合(テレメトリデータフォワーダなど)を含みます。 36 | 37 | 40 | 41 | - デシリアライズされたデータを効率的に修正し、さらに渡すために再びシリアライズする機能をサポートすること。これは関連はしていますが、先ほどの要件とは少し異なります。 42 | 43 | 46 | 47 | - 高遅延ネットワークでの高スループット(利用可能な帯域幅)を確保すること。(例:テレメトリソースとバックエンドが高遅延ネットワークで分離されているシナリオ) 48 | 49 | 52 | 53 | - バックプレッシャー・シグナリングを可能にすること 54 | 55 | 58 | 59 | - ロードバランサーフレンドリーであること(リバランシングの妨げにならないこと) 60 | 61 | -------------------------------------------------------------------------------- /specification/specification/protocol/exporter.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # OpenTelemetry Protocol Exporter 6 | 7 | **Status**: [Stable](../document-status.md) 8 | 9 | 12 | 13 | 本ドキュメントは、OpenTelemetry Protocol ([OTLP](https://github.com/open-telemetry/oteps/blob/main/text/0035-opentelemetry-protocol.md)) Exporterで利用可能な設定オプションと、リトライの動作について規定しています。 14 | 15 | 18 | 19 | ## 設定オプション 20 | 21 | 24 | 25 | OTLP Exporterを構成するために、以下の構成オプションが利用可能でなければなりません(MUST)。また、各設定オプションは、Signal固有のオプションでオーバーライド可能でなければなりません(MUST)。 26 | 27 | 36 | 37 | | Configuration Option | 説明 | Default | 環境変数名 | 38 | | -------------------- | ------------------------------------------------------------ | ----------------- | ------------------------------------------------------------ | 39 | | Endpoint | ExporterがSpanやMetricsを送信する先のターゲット。エンドポイントは、スキーム(httpまたはhttps)とホストを持つ有効なURLでなければならず(MUST)、ポートとパスを含んでもかまいません(MAY)。スキームが https の場合は、安全な接続を示します。OTLP/HTTP で `OTEL_EXPORTER_OTLP_ENDPOINT` を使用する場合、エクスポートする側は、バージョンとシグナルをパスに追加するというコレクターの慣習に従うべきです(SHOULD) (例: `v1/traces` や `v1/metrics`)。Signalごとのエンドポイント設定オプションが優先され、この動作をオーバーライドするために使用することができます。詳しくは[OTLP仕様書][otlphttp-req]を参照してください。| `https://localhost:4317` | `OTEL_EXPORTER_OTLP_ENDPOINT` `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | 40 | | Certificate File | gRPCクライアントのTLS認証用証明書ファイルへのパス。安全な接続のためにのみ使用してください。| n/a | `OTEL_EXPORTER_OTLP_CERTIFICATE` `OTEL_EXPORTER_OTLP_TRACES_CERTIFICATE` `OTEL_EXPORTER_OTLP_METRICS_CERTIFICATE` | 41 | | Headers | gRPCやHTTPリクエストに関連するヘッダーとして使用されるキーと値のペアです。詳しくは、[Specifying headers](./exporter.md#specifying-headers-via-environment-variables)をご覧ください。 | n/a | `OTEL_EXPORTER_OTLP_HEADERS` `OTEL_EXPORTER_OTLP_TRACES_HEADERS` `OTEL_EXPORTER_OTLP_METRICS_HEADERS` | 42 | | Compression | サポートされている圧縮タイプの圧縮キーです。サポートされている圧縮形式:`gzip`。| No value | `OTEL_EXPORTER_OTLP_COMPRESSION` `OTEL_EXPORTER_OTLP_TRACES_COMPRESSION` `OTEL_EXPORTER_OTLP_METRICS_COMPRESSION` | 43 | | Timeout | OTLPエクスポーターが各バッチのエクスポートで待機する最大時間 | 10s | `OTEL_EXPORTER_OTLP_TIMEOUT` `OTEL_EXPORTER_OTLP_TRACES_TIMEOUT` `OTEL_EXPORTER_OTLP_METRICS_TIMEOUT` | 44 | 45 | 48 | 49 | `OTEL_EXPORTER_OTLP_*COMPRESSION`オプションでサポートされる値: 50 | 51 | 55 | 56 | - この値がない場合は、圧縮は無効です。 57 | - 今のところ、`gzip`が唯一の圧縮方法として指定されています。その他のオプションは言語 SDK でサポートされていても構いません(MAY)。各言語のドキュメントを参照してください。 58 | 59 | 62 | 63 | 例 1 64 | 65 | 68 | 69 | 以下の構成では、すべてのSignalが同じコレクターに送られます。 70 | 71 | 76 | 77 | ```bash 78 | export OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4317 79 | ``` 80 | 81 | 84 | 85 | 例 2 86 | 87 | 90 | 91 | TraceやMetricsは、異なるCollectorに送られます。 92 | 93 | ```bash 94 | export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://collector:4317 95 | 96 | export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://collector.example.com/v1/metrics 97 | ``` 98 | 99 | 102 | 103 | ### プロトコルの指定 104 | 105 | 112 | 113 | 現在、OTLPは、`grpc`、`http/json`、`http/protobuf`など、サポートできるトランスポートプロトコルが複数あります。仕様書の1.0の時点では、*指定されたデフォルトはなく、環境変数による設定もありません*。今後のプロトコルの設定のために、以下の環境変数を予約しています。 114 | 115 | 120 | 121 | - `OTEL_EXPORTER_OTLP_PROTOCOL` 122 | - `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL` 123 | - `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL` 124 | 125 | 128 | 129 | SDKは、設定が提供されていない場合、不特定のデフォルトを持っています。 130 | 131 | 134 | 135 | ### 環境変数によるヘッダーの指定 136 | 137 | 140 | 141 | 環境変数 `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_TRACES_HEADERS`, `OTEL_EXPORTER_OTLP_METRICS_HEADERS` には、キーバリューペアのリストが格納され、これらは [W3C Correlation-Context](https://github.com/w3c/baggage/blob/master/baggage/HTTP_HEADER_FORMAT.md)に一致するフォーマットで表現されることが期待されます(例: key1=value1,key2=value2)。ただし、追加のセミコロンで区切られたメタデータはサポートされていません。すべての属性値は文字列とみなされなければなりません(MUST)。 142 | 143 | 146 | 147 | ## リトライ 148 | 149 | 152 | 153 | 一時的なエラーは、リトライ戦略で処理しなければなりません(MUST)。このリトライ戦略は、ネットワークが復旧するまで、あるいは送信先が回復するまで、送信先に負担をかけないように、ジッターを含む指数関数的なバックオフを実装しなければなりません(MUST)。 154 | 155 | 158 | 159 | OTLP/HTTPでは、エラー`408 (Request Timeout)`と`5xx (Server Errors)`が一時的なエラーとして定義されています。エラーに関する詳細な情報は、[HTTP failures section](otlp.md#failures)に記載されています。OTLP/gRPCでは、gRPCのリトライ可能なステータスコードの一覧は、[gRPC response section](otlp.md#otlpgrpc-response)に記載されています。 160 | 161 | 164 | 165 | [otlphttp-req]: otlp.md#otlphttp-request 166 | 167 | -------------------------------------------------------------------------------- /specification/specification/protocol/img/otlp-client-server.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/protocol/img/otlp-client-server.png -------------------------------------------------------------------------------- /specification/specification/protocol/img/otlp-concurrent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/protocol/img/otlp-concurrent.png -------------------------------------------------------------------------------- /specification/specification/protocol/img/otlp-multi-destination.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/protocol/img/otlp-multi-destination.png -------------------------------------------------------------------------------- /specification/specification/protocol/img/otlp-request-response.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/protocol/img/otlp-request-response.png -------------------------------------------------------------------------------- /specification/specification/protocol/img/otlp-sequential.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/open-telemetry/docs-ja/3561b9553dafdcb88f7f40eb049a3ef059fc00b3/specification/specification/protocol/img/otlp-sequential.png -------------------------------------------------------------------------------- /specification/specification/resource/sdk.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # リソース SDK 6 | 7 | 10 | 11 | **Status**: [Stable](../document-status.md) 12 | 13 | 22 | 23 | [リソース](../overview.md#resources)は、テレメトリを生成するエンティティを[属性](../common/common.md#attributes)として不変的に表現したものです。例えば、Kubernetes上のコンテナで実行されているテレメトリを生成するプロセスは、Pod名を持ち、Namespace内にあり、おそらく名前を持つDeploymentの一部です。これらの3つの属性はすべて`リソース`に含めることができます。なお、意味が決まっている["標準属性"](semantic_conventions/README.md)があります。 24 | 25 | 32 | 33 | リソースをSDKのファーストクラスのコンセプトとした主な目的は、リソース情報の発見をエクスポーターから切り離すことです。これにより、独立した開発が可能になり、クローズドソース環境との統合を必要とするユーザーのためのカスタマイズが容易になります。SDKは、`リソース`の作成と、それをテレメトリに関連付けることを可能にしなければなりません(MUST)。 34 | 35 | 42 | 43 | 分散トレーシングで使用する場合、TracerProviderが作成された時点で、リソースを[`TracerProvider`](../trace/api.md#tracerprovider)に関連付けることができます。その関連付けは後から変更することはできません。`TracerProvider`と関連付けられた場合、プロバイダからのあらゆる`Tracer`によって生成されたすべての`Span`は、この`リソース`と関連付けられなければなりません(MUST)。 44 | 45 | 52 | 53 | 分散トレーシングと同様に、Metricsを使用する場合、リソースは `MeterProvider` と関連付けることができます。[`MeterProvider`](../metrics/api.md#meter-interface)に関連付けられると、そのプロバイダからの任意の`Meter`によって生成されたすべてのメトリックは、この`リソース`に関連付けられます。 54 | 55 | 58 | 59 | ## SDKが提供する リソース属性 60 | 61 | 67 | 68 | SDKは、[Semantic Attributes with SDK-provided Default Value](semantic_conventions/README.md#semantic-attributes-with-sdk-provided-default-value)に記載されている属性を少なくとも持つResourceへのアクセスを提供しなければなりません(MUST)。他のリソースが明示的に指定されていない場合、このリソースは、`TracerProvider`または`MeterProvider`と関連付けられなければなりません(MUST)。 69 | 70 | 79 | 80 | 注:これは、SDKが提供する属性のすべてまたは一部が存在しないリソースを作成して関連付けることが可能であることを意味します。しかし、それはデフォルトでは起こりません。ユーザーがデフォルトのリソースにカスタム属性を組み合わせたい場合は、[`Merge`](#merge)をカスタムリソースに使用するか、リソースを明示的に関連付ける代わりに、[環境からリソース情報を検出する](#環境からリソース情報を検出する)を実装して属性を指定します。 81 | 82 | 83 | 86 | 87 | ## リソースの作成 88 | 89 | 92 | 93 | SDKは、新しいリソースをインスタンス化する2つの方法をサポートする必要があります。それらは以下の２つです: 94 | 95 | 96 | 99 | 100 | ### Create 101 | 102 | 107 | 108 | インターフェースは、[`Attributes`](../common/common.md#attributes)から、新しいリソースを作成する方法を提供しなければなりません(MUST)。例えば、リソースオブジェクトのファクトリーメソッドやコンストラクタなどです。キャッシュされたオブジェクトのサポートを可能にするために、ファクトリーメソッドを推奨します。 109 | 110 | 113 | 114 | 必須パラメータ: 115 | 116 | 119 | 120 | - [`Attributes`](../common/common.md#attributes) 121 | 122 | 125 | 126 | ### Merge 127 | 128 | 132 | 133 | インターフェースは、古いリソースと更新中のリソースを新しいリソースに統合する方法を提供しなければなりません(MUST)。 134 | 135 | 140 | 141 | 注:これは、環境変数や、ホストやコンテナから抽出されたメタデータなど、異なるソースから属性を得ているリソースをマージするために使用することを目的としています。 142 | 143 | 148 | 149 | 結果として得られるリソースは、2つの入力リソースのいずれかに存在するすべての属性を持たなければなりません(MUST)。旧リソースと更新リソースの両方にキーが存在する場合、(更新値が空であっても)更新リソースの値が選ばれなければなりません(MUST)。 150 | 151 | 154 | 155 | 必須パラメータ: 156 | 157 | 161 | 162 | - 古いリソース 163 | - 属性が優先される更新リソース 164 | 165 | 168 | 169 | ### 空リソース 170 | 171 | 175 | 176 | 空のリソースを素早く作成する方法を提供することが推奨されていますが、必須ではありません。 177 | 178 | 181 | 182 | ### 環境からリソース情報を検出する 183 | 184 | 189 | 190 | 一般的なプラットフォーム(Docker、Kubernetesなど)やベンダー固有の環境(EKS、AKS、GKEなど)に関連するカスタムリソース検出器は、SDKとは別のパッケージとして実装しなければなりません(MUST)。 191 | 192 | 197 | 198 | リソース検出器パッケージは、リソースを返すメソッドを提供しなければなりません(MUST)。これにより、上述のように、`TracerProvider` や `MeterProvider` のインスタンスと関連付けられます。 199 | 200 | 205 | 206 | リソース検出器パッケージは、複数のソースからリソース情報を検出し、その結果を前述の `Merge` 操作でマージしても構いません(MAY)。 207 | 208 | 217 | 218 | このコードはアプリケーションの初期化時に実行されるため、リソース検出ロジックは短時間で完了することが期待されます。エラーは、[エラー処理の原則](../error-handling.md#basic-error-handling-principles)で指定されているように処理されるべきです。なお、リソース情報の検出に失敗した場合はエラーとみなしてはいけません(MUST NOT)が、リソース情報を検出しようとした際に発生したエラーはエラーとみなすべきです(SHOULD)。 219 | 220 | 223 | 224 | ### 環境変数によるリソース情報の指定 225 | 226 | 232 | 233 | SDKは、環境変数`OTEL_RESOURCE_ATTRIBUTES`から情報を抽出し、これを二次リソースとして、ユーザーが提供したリソース情報と[マージ](#merge)しなければなりません(つまり、ユーザーが提供したリソース情報の方が優先されます)。 234 | 235 | 242 | 243 | 環境変数 `OTEL_RESOURCE_ATTRIBUTES` には、キーと値のペアのリストが含まれます。これらは、セミコロンで区切られた追加のメタデータがサポートされていないことを除いて、[W3C Baggage](https://github.com/w3c/baggage/blob/fdc7a5c4f4a31ba2a36717541055e551c2b032e4/baggage/HTTP_HEADER_FORMAT.md#header-content)に沿ったフォーマットで表現されることが期待されています(例:`key1=value1,key2=value2`)。すべての属性値は文字列とみなされなければなりません(MUST)。 244 | 245 | 248 | 249 | ## リソース操作 250 | 251 | 255 | 256 | リソースは不変(Immutable)です。したがって、リソースの作成に加えて、以下のような操作のみを提供する必要があります。 257 | 258 | 261 | 262 | ### 属性の取得 263 | 264 | 268 | 269 | SDKは、リソースに関連付けられた属性の読み取り専用の属性集合(Collection)を取得する方法を提供する必要があります。 270 | 271 | 274 | 275 | 属性の順番を保証する必要はありません。 276 | 277 | 283 | 284 | 属性を取得する際の最も一般的な操作は、その属性を列挙(enumerate)することです。そのため、特定のキーを持つ属性の値を素早く取得する方法などの他の考慮事項よりも、高速に列挙できるように結果の集合(Collection)を最適化することが推奨されます。 285 | 286 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/cloud.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # クラウド 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | **type:** `cloud` 10 | 11 | 14 | 15 | **Description:** クラウドインフラストラクチャ (e.g. GCP, Azure, AWS). 16 | 17 | 18 | 19 | | Attribute | Type | Description | Examples | Required | 20 | |---|---|---|---|---| 21 | | `cloud.provider` | string | クラウドプロバイダの名前 | `gcp` | No | 22 | | `cloud.account.id` | string | リソースが割り当てられているクラウドのアカウントID | `111111111111`; `opentelemetry` | No | 23 | | `cloud.region` | string | リソースが動作している地理的な地域。[AWSリージョン](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)、[Azureリージョン](https://azure.microsoft.com/en-us/global-infrastructure/geographies/)、[Google Cloudリージョン](https://cloud.google.com/about/locations)など、利用可能なリージョンについては、プロバイダーのドキュメントを参照してください。 | `us-central1`; `us-east-1` | No | 24 | | `cloud.availability_zone` | string | クラウドのリージョンは、可用性を高めるために、ゾーンと呼ばれる複数の隔離された場所を持つことが多いです。アベイラビリティゾーンは、リソースが稼働しているゾーンを表します。 [1] | `us-east-1c` | No | 25 | | `cloud.platform` | string | 使用中のクラウドプラットフォームのリソース [2] | `aws_ec2`; `azure_vm`; `gcp_compute_engine` | No | 26 | 27 | **[1]:** Google Cloudでは、アベイラビリティー・ゾーンを"Zone"と呼んでいます。 28 | 29 | **[2]:** サービスのプレフィックスは `cloud.provider` で指定されたものと一致するべきです(SHOULD)。 30 | 31 | `cloud.provider` MUST be one of the following or, if none of the listed values apply, a custom value: 32 | 33 | | Value | Description | 34 | |---|---| 35 | | `aws` | Amazon Web Services | 36 | | `azure` | Microsoft Azure | 37 | | `gcp` | Google Cloud Platform | 38 | 39 | `cloud.platform` MUST be one of the following or, if none of the listed values apply, a custom value: 40 | 41 | | Value | Description | 42 | |---|---| 43 | | `aws_ec2` | AWS Elastic Compute Cloud | 44 | | `aws_ecs` | AWS Elastic Container Service | 45 | | `aws_eks` | AWS Elastic Kubernetes Service | 46 | | `aws_lambda` | AWS Lambda | 47 | | `aws_elastic_beanstalk` | AWS Elastic Beanstalk | 48 | | `azure_vm` | Azure Virtual Machines | 49 | | `azure_container_instances` | Azure Container Instances | 50 | | `azure_aks` | Azure Kubernetes Service | 51 | | `azure_functions` | Azure Functions | 52 | | `azure_app_service` | Azure App Service | 53 | | `gcp_compute_engine` | Google Cloud Compute Engine (GCE) | 54 | | `gcp_cloud_run` | Google Cloud Run | 55 | | `gcp_kubernetes_engine` | Google Cloud Kubernetes Engine (GKE) | 56 | | `gcp_cloud_functions` | Google Cloud Functions (GCF) | 57 | | `gcp_app_engine` | Google Cloud App Engine (GAE) | 58 | 59 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/cloud_provider/aws/README.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # AWS セマンティック規約 6 | 7 | 10 | 11 | **Status**: [Experimental](../../../../document-status.md) 12 | 13 | 19 | 20 | このディレクトリでは、Amazon Web Services (AWS)のリソースにのみ適用されるリソース属性の標準を定義しています。もしある属性が複数のクラウドプロバイダーのリソースに適用される可能性がある場合(アカウントIDやオペレーティングシステムなど)、その属性は親ディレクトリである `semantic_conventions` に属します。 21 | 22 | 25 | 26 | ## 一般的な AWS 属性 27 | 28 | 32 | 33 | AWSに関連する属性、またはAWS固有の用語を使用しているが、AWS内の複数のサービスで使用されていたり、特定のサービスから抽象化されていたりする属性。 34 | 35 | 38 | 39 | - [AWS Logs](./logs.md) 40 | 41 | 44 | 45 | ## サービス 46 | 47 | 50 | 51 | 個々のAWSサービスに関連する属性。 52 | 53 | 56 | 57 | - [Elastic Container Service (ECS)](./ecs.md) 58 | - [Elastic Kubernetes Service (EKS)](./eks.md) 59 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/cloud_provider/aws/ecs.md: -------------------------------------------------------------------------------- 1 | # AWS ECS 2 | 3 | **Status**: [Experimental](../../../../document-status.md) 4 | 5 | **type:** `aws.ecs` 6 | 7 | **Description:** AWS Elastic Container Service(ECS)が使用するリソースです。 8 | 9 | 10 | | Attribute | Type | Description | Examples | Required | 11 | |---|---|---|---|---| 12 | | `aws.ecs.container.arn` | string | [ECSコンテナインスタンス](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_instances.html)のAmazon Resource Name(ARN)。 | `arn:aws:ecs:us-west-1:123456789123:container/32624152-9086-4f0e-acae-1a75b14fe4d9` | No | 13 | | `aws.ecs.cluster.arn` | string | [ECSクラスタ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html)のARN。 | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | No | 14 | | `aws.ecs.launchtype` | string | ECSタスクの[起動タイプ](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html)。 | `ec2`; `fargate` | No | 15 | | `aws.ecs.task.arn` | string | [ECSタスク定義](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html)のARN。 | `arn:aws:ecs:us-west-1:123456789123:task/10838bed-421f-43ef-870a-f43feacbbb5b` | No | 16 | | `aws.ecs.task.family` | string | このタスク定義が属するタスク定義ファミリ。 | `opentelemetry-family` | No | 17 | | `aws.ecs.task.revision` | string | このタスク定義のリビジョン | `8`; `26` | No | 18 | 19 | `aws.ecs.launchtype` MUST be one of the following: 20 | 21 | | Value | Description | 22 | |---|---| 23 | | `ec2` | ec2 | 24 | | `fargate` | fargate | 25 | 26 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/cloud_provider/aws/eks.md: -------------------------------------------------------------------------------- 1 | # AWS EKS 2 | 3 | **Status**: [Experimental](../../../../document-status.md) 4 | 5 | **type:** `aws.eks` 6 | 7 | **Description:** AWS Elastic Kubernetes Service(EKS)が使用するリソースです。 8 | 9 | 10 | | Attribute | Type | Description | Examples | Required | 11 | |---|---|---|---|---| 12 | | `aws.eks.cluster.arn` | string | EKSクラスターのARN | `arn:aws:ecs:us-west-2:123456789123:cluster/my-cluster` | No | 13 | 14 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/cloud_provider/aws/logs.md: -------------------------------------------------------------------------------- 1 | # AWS Logs 2 | 3 | **Status**: [Experimental](../../../../document-status.md) 4 | 5 | **Type:** `aws.log` 6 | 7 | **Description:** Amazon Web Servicesのログ属性です。 8 | 9 | 10 | | Attribute | Type | Description | Examples | Required | 11 | |---|---|---|---|---| 12 | | `aws.log.group.names` | string[] | アプリケーションが書き込んでいるAWS log groupの名前。 [1] | `[/aws/lambda/my-function, opentelemetry-service]` | No | 13 | | `aws.log.group.arns` | string[] | AWSロググループのAmazon Resource Name(ARN)。 [2] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:*]` | No | 14 | | `aws.log.stream.names` | string[] | アプリケーションが書き込んでいるAWSログストリームの名前。 | `[logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | No | 15 | | `aws.log.stream.arns` | string[] | AWSログストリームのARN。 [3] | `[arn:aws:logs:us-west-1:123456789012:log-group:/aws/my/group:log-stream:logs/main/10838bed-421f-43ef-870a-f43feacbbb5b]` | No | 16 | 17 | **[1]:** マルチコンテナアプリケーションのように1つのアプリケーションにサイドカーコンテナがあり、それぞれがそれぞれのロググループに書き込むような場合があるため、複数のロググループをサポートする必要があります。 18 | 19 | **[2]:** [ロググループ ARN 形式のドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format) を参照してください。 20 | 21 | **[3]:** [ログストリーム ARN 形式のドキュメント](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/iam-access-control-overview-cwl.html#CWL_ARN_Format)を参照してください。1つのロググループには複数のログストリームを含むことができるので、これらのARNは必然的にロググループとログストリームの両方を識別する必要があります。 22 | 23 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/container.md: -------------------------------------------------------------------------------- 1 | # Container 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | **type:** `container` 6 | 7 | 10 | 11 | **Description:** コンテナインスタンスです。 12 | 13 | 14 | | Attribute | Type | Description | Examples | Required | 15 | |---|---|---|---|---| 16 | | `container.name` | string | コンテナ名 | `opentelemetry-autoconf` | No | 17 | | `container.id` | string | コンテナID。通常はUUIDで、例えば[Dockerコンテナの識別子](https://docs.docker.com/engine/reference/run/#container-identification)]に使用されます。UUIDが略されている場合があります。 | `a3bf90e006b2` | No | 18 | | `container.runtime` | string | このコンテナを管理しているコンテナランタイム | `docker`; `containerd`; `rkt` | No | 19 | | `container.image.name` | string | コンテナイメージの名前 | `gcr.io/opentelemetry/operator` | No | 20 | | `container.image.tag` | string | コンテナイメージタグ | `0.1` | No | 21 | 22 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/deployment_environment.md: -------------------------------------------------------------------------------- 1 | # Deployment 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | **type:** `deployment` 6 | 7 | 10 | 11 | **Description:** ソフトウェアのデプロイです。 12 | 13 | 14 | | Attribute | Type | Description | Examples | Required | 15 | |---|---|---|---|---| 16 | | `deployment.environment` | string | [デプロイ環境](https://en.wikipedia.org/wiki/Deployment_environment)の名前(別名:配置層) | `staging`; `production` | No | 17 | 18 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/faas.md: -------------------------------------------------------------------------------- 1 | # Function as a Service 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | **type:** `faas` 6 | 7 | 10 | 11 | **Description:** サーバーレスのインスタンスです。 12 | 13 | 14 | | Attribute | Type | Description | Examples | Required | 15 | |---|---|---|---|---| 16 | | `faas.name` | string | 実行される関数名 | `my-function` | Yes | 17 | | `faas.id` | string | 実行される関数の一意なID [1] | `arn:aws:lambda:us-west-2:123456789012:function:my-function` | Yes | 18 | | `faas.version` | string | [バージョン属性](.../.../resource/semantic_conventions/README.md#version-attributes)で定義されている、実行される関数のバージョン文字列。 | `2.0.0` | No | 19 | | `faas.instance` | string | 実行環境のID文字列。 | `my-function:instance-0001` | No | 20 | | `faas.max_memory` | int | サーバーレス関数を実行する際のメモリをMiBで記述したもの [2] | `128` | No | 21 | 22 | **[1]:** このフィールドは、例えばAWS Lambdaでは[ARN](https://docs.aws.amazon.com/general/latest/gr/aws-arns-and-namespaces.html)の値に、GCPではリソースのURIに、Azureでは[FunctionDirectory](https://github.com/Azure/azure-functions-host/wiki/Retrieving-information-about-the-currently-running-function)の値に対応しています。 23 | 24 | **[2]:** メモリが少なすぎるとJavaのAWS Lambda関数が正常に動作しなくなることがあるので、この属性を設定しておくことをお勧めします。AWS Lambda上では、環境変数 `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` がこの情報を提供します。 25 | 26 | 27 | 注:Resource属性の`faas.instance`は、Span属性の`faas.execution`とは異なります。詳細は[FaaS spanのセマンティック規約](../../trace/semantic_conventions/faas.md#difference-between-execution-and-instance)を参照してください。 28 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/host.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # ホスト 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | **type:** `host` 10 | 11 | 14 | 15 | **Description:** ホストとは、一般的なコンピューティングインスタンスと定義されます。 16 | 17 | 18 | | Attribute | Type | Description | Examples | Required | 19 | |---|---|---|---|---| 20 | | `host.id` | string | 一意のホスト ID。クラウドの場合、これはクラウドプロバイダーによって割り当てられた instance_id である必要があります。 | `opentelemetry-test` | No | 21 | | `host.name` | string | ホストの名前。Unix システムでは、hostname コマンドが返すもの、完全修飾されたホスト名、あるいはユーザが指定した別の名前が含まれます。 | `opentelemetry-test` | No | 22 | | `host.type` | string | ホストの種類。クラウドの場合は、マシンタイプである必要があります。 | `n1-standard-1` | No | 23 | | `host.arch` | string | ホストシステムが動いているCPUアーキテクチャ | `amd64` | No | 24 | | `host.image.name` | string | ホストがインスタンス化されたVMイメージまたはOSのインストール名。 | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` | No | 25 | | `host.image.id` | string | VM イメージ ID。クラウドの場合、この値はプロバイダのものです。 | `ami-07b06b442921831e5` | No | 26 | | `host.image.version` | string | [バージョン属性](README.md#version-attributes)で定義されているVMイメージのバージョン文字列。 | `0.1` | No | 27 | 28 | `host.arch` MUST be one of the following or, if none of the listed values apply, a custom value: 29 | 30 | | Value | Description | 31 | |---|---| 32 | | `amd64` | AMD64 | 33 | | `arm32` | ARM32 | 34 | | `arm64` | ARM64 | 35 | | `ia64` | Itanium | 36 | | `ppc32` | 32-bit PowerPC | 37 | | `ppc64` | 64-bit PowerPC | 38 | | `x86` | 32-bit x86 | 39 | 40 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/k8s.md: -------------------------------------------------------------------------------- 1 | # Kubernetes 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | 8 | 9 | Kubernetesのオブジェクトやメタデータを理解するのに役立つリソースです。 10 | 11 | 17 | 18 | * [Namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) 19 | * [Names and UIDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/). 20 | * [Pods](https://kubernetes.io/docs/concepts/workloads/pods/) 21 | * [Controllers](https://kubernetes.io/docs/concepts/workloads/controllers/) 22 | 23 | 29 | 30 | Kubernetesオブジェクトの "name" は、 "namespace" 内のその種類のオブジェクトに対して一意であり、特定の瞬間にのみ有効です(名前は時間の経過とともに再利用できます)。"uid" は、クラスタ全体で一意であり、時間を超えても一意である可能性が高いです。このため、すべてのKubernetesオブジェクトにUIDを設定することが推奨されていますが、通常は "name" の方がユーザーフレンドリーなので、こちらも設定可能です。 31 | 32 | 35 | 36 | ## クラスター 37 | 38 | **type:** `k8s.cluster` 39 | 40 | 42 | 43 | **説明:** kubernetes Cluster 44 | 45 | 46 | | Attribute | Type | Description | Examples | Required | 47 | |---|---|---|---|---| 48 | | `k8s.cluster.name` | string | クラスターの名前。 | `opentelemetry-cluster` | No | 49 | 50 | 51 | 54 | 55 | ## Node 56 | 57 | **type:** `k8s.node` 58 | 59 | 62 | 63 | **説明:** Kubernetes Node 64 | 65 | 66 | | Attribute | Type | Description | Examples | Required | 67 | |---|---|---|---|---| 68 | | `k8s.node.name` | string | Nodeの名前 | `node-1` | No | 69 | | `k8s.node.uid` | string | NodeのUID | `1eb3a0c6-0477-4080-a9cb-0cb7db65c6a2` | No | 70 | 71 | 72 | 75 | 76 | ## Namespace 77 | 78 | 82 | 83 | Namespaceは、nameの範囲を提供します。オブジェクトの名前は、namespace内では一意である必要がありますが、namespace間では一意ではありません。 84 | 85 | **type:** `k8s.namespace` 86 | 87 | 90 | 91 | **説明:** Kubernetes Namespace 92 | 93 | 94 | | Attribute | Type | Description | Examples | Required | 95 | |---|---|---|---|---| 96 | | `k8s.namespace.name` | string | Podが動作しているnamespaceの名前 | `default` | No | 97 | 98 | 99 | 102 | 103 | ## Pod 104 | 105 | 108 | 109 | 最小かつ最もシンプルなKubernetesのオブジェクト。Podは、クラスタ上で稼働するコンテナのセットを表します。 110 | 111 | **type:** `k8s.pod` 112 | 113 | 116 | 117 | **説明:** Kubernetes Pod オブジェクト 118 | 119 | 120 | | Attribute | Type | Description | Examples | Required | 121 | |---|---|---|---|---| 122 | | `k8s.pod.uid` | string | PodのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 123 | | `k8s.pod.name` | string | Podの名前 | `opentelemetry-pod-autoconf` | No | 124 | 125 | 126 | 129 | 130 | ## Container 131 | 132 | 137 | 138 | Podテンプレート内のコンテナの仕様です。このタイプは、実行中のコンテナの名前とは異なるPodテンプレート内のコンテナの名前などの情報を取得するために使用することを目的としています。 139 | 140 | 144 | 145 | 注:このタイプは、実行中のコンテナに対応する[container](./container.md)とは異なります。 146 | 147 | **type:** `k8s.container` 148 | 149 | 152 | 153 | **説明:** [PodTemplate](https://kubernetes.io/docs/concepts/workloads/pods/#pod-templates)のコンテナです。 154 | 155 | 156 | | Attribute | Type | Description | Examples | Required | 157 | |---|---|---|---|---| 158 | | `k8s.container.name` | string | PodTemplate の中のコンテナの名前 | `redis` | No | 159 | 160 | 161 | 164 | 165 | ## ReplicaSet 166 | 167 | 171 | 172 | ReplicaSetの目的は、常に安定したレプリカPodのセットを実行することです。 173 | 174 | **type:** `k8s.replicaset` 175 | 176 | 179 | 180 | **説明:** Kubernetes ReplicaSet オブジェクト 181 | 182 | 183 | | Attribute | Type | Description | Examples | Required | 184 | |---|---|---|---|---| 185 | | `k8s.replicaset.uid` | string | ReplicaSetのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 186 | | `k8s.replicaset.name` | string | ReplicaSetの名前 | `opentelemetry` | No | 187 | 188 | 189 | 192 | 193 | ## Deployment 194 | 195 | 200 | 201 | 複製されたアプリケーションを管理するAPIオブジェクトで、通常、ローカルステートを持たないPodを実行します。各レプリカはPodで表現され、Podはクラスタのノードに分散されます。 202 | 203 | **type:** `k8s.deployment` 204 | 205 | 208 | 209 | **説明:** Kubernetes Deployment オブジェクト 210 | 211 | 212 | | Attribute | Type | Description | Examples | Required | 213 | |---|---|---|---|---| 214 | | `k8s.deployment.uid` | string | DeploymentのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 215 | | `k8s.deployment.name` | string | Deploymentの名前 | `opentelemetry` | No | 216 | 217 | 218 | 221 | 222 | ## StatefulSet 223 | 224 | 228 | 229 | 一連のPodのデプロイとスケーリングを管理し、これらのPodの順序と一意性に関する保証を提供します。 230 | 231 | **type:** `k8s.statefulset` 232 | 233 | 236 | 237 | **説明:** Kubernetes StatefulSet オブジェクト 238 | 239 | 240 | 241 | | Attribute | Type | Description | Examples | Required | 242 | |---|---|---|---|---| 243 | | `k8s.statefulset.uid` | string | StatefulSetのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 244 | | `k8s.statefulset.name` | string | StatefulSetの名前 | `opentelemetry` | No | 245 | 246 | 247 | 250 | 251 | ## DaemonSet 252 | 253 | 256 | 257 | DaemonSetは、すべての(または一部の)NodeがPodのコピーを実行することを保証します。 258 | 259 | 262 | 263 | **type:** `k8s.daemonset` 264 | 265 | 268 | 269 | **説明:** Kubernetes DaemonSet オブジェクト 270 | 271 | 272 | 273 | | Attribute | Type | Description | Examples | Required | 274 | |---|---|---|---|---| 275 | | `k8s.daemonset.uid` | string | DaemonSetのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 276 | | `k8s.daemonset.name` | string | DaemonSetの名前 | `opentelemetry` | No | 277 | 278 | 279 | 282 | 283 | ## Job 284 | 285 | 289 | 290 | ジョブは、1つまたは複数のPodを作成し、そのうちの指定された数のPodが正常に終了することを保証します。 291 | 292 | 295 | 296 | **type:** `k8s.job` 297 | 298 | 301 | 302 | **説明:** Kubernetes Job オブジェクト 303 | 304 | 305 | | Attribute | Type | Description | Examples | Required | 306 | |---|---|---|---|---| 307 | | `k8s.job.uid` | string | JobのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 308 | | `k8s.job.name` | string | Jobの名前 | `opentelemetry` | No | 309 | 310 | 311 | 314 | 315 | ## CronJob 316 | 317 | 320 | 321 | CronJobは、繰り返しのスケジュールでジョブを作成します。 322 | 323 | 326 | 327 | **type:** `k8s.cronjob` 328 | 329 | 332 | 333 | **例:** Kubernetes CronJobオブジェクト 334 | 335 | 336 | | Attribute | Type | Description | Examples | Required | 337 | |---|---|---|---|---| 338 | | `k8s.cronjob.uid` | string | CronJobのUID | `275ecb36-5aa8-4c2a-9c47-d8bb681b9aff` | No | 339 | | `k8s.cronjob.name` | string | CronJobの名前 | `opentelemetry` | No | 340 | 341 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/os.md: -------------------------------------------------------------------------------- 1 | # Operating System 2 | 3 | **Status**: [Experimental](../../document-status.md) 4 | 5 | **type:** `os` 6 | 7 | 10 | 11 | **Description**: このリソースで表されるプロセスが実行されているオペレーティング・システム(OS)。 12 | 13 | 16 | 17 | 仮想化環境の場合、これはプロセスによって観察されるオペレーティングシステムであり、基礎となるホストではなく仮想化されたゲストです。 18 | 19 | 20 | | Attribute | Type | Description | Examples | Required | 21 | |---|---|---|---|---| 22 | | `os.type` | string | The operating system type. | `windows` | Yes | 23 | | `os.description` | string | 人間が読める (解析を意図していない) OS のバージョン情報で、例えば `ver` や `lsb_release -a` コマンドで得られるような文字列です。 | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | No | 24 | 25 | `os.type` MUST be one of the following or, if none of the listed values apply, a custom value: 26 | 27 | | Value | Description | 28 | |---|---| 29 | | `windows` | Microsoft Windows | 30 | | `linux` | Linux | 31 | | `darwin` | Apple Darwin | 32 | | `freebsd` | FreeBSD | 33 | | `netbsd` | NetBSD | 34 | | `openbsd` | OpenBSD | 35 | | `dragonflybsd` | DragonFly BSD | 36 | | `hpux` | HP-UX (Hewlett Packard Unix) | 37 | | `aix` | AIX (Advanced Interactive eXecutive) | 38 | | `solaris` | Oracle Solaris | 39 | | `z_os` | IBM z/OS | 40 | -------------------------------------------------------------------------------- /specification/specification/resource/semantic_conventions/webengine.md: -------------------------------------------------------------------------------- 1 | # Webengine 2 | 3 | **type:** `webengine` 4 | 5 | 8 | 9 | **Description:** アプリケーションコードを実行するパッケージソフトウェアを記述するリソース。Webエンジンは、通常、process.runtimeを使用して実行されます。 10 | 11 | 12 | | Attribute | Type | Description | Examples | Required | 13 | |---|---|---|---|---| 14 | | `webengine.name` | string | Webエンジンの名前 | `WildFly` | Yes | 15 | | `webengine.version` | string | Webエンジンのバージョン | `21.0.0` | No | 16 | | `webengine.description` | string | Webエンジンの追加説明(詳細なバージョンとエディション情報など) | `WildFly Full 21.0.0.Final (WildFly Core 13.0.1.Final) - 2.2.2.Final` | No | 17 | 18 | 19 | 22 | 23 | Webエンジンの情報は、Webエンジンが提供するAPIから取得した値を用いて取得すべきであり、エンジンのバージョンアップに伴うメンテナンスの負担を避けるために、できればランタイム中に取得すべきです(SHOULD)。例として、Javaエンジンはアプリケーションサーバーとしてパッケージ化されていることが多いですが、必ずしもそうではありません。Servlet APIをサポートするJavaアプリケーションサーバの場合、必要な情報は、実行時に`ServletContext.getServerInfo()`を呼び出し、その結果を解析することで取得しても構いません(MAY)。 24 | 25 | 28 | 29 | 1つのリソースは、最大で1つのウェブエンジンに帰属します。 30 | 31 | 34 | 35 | 複数の候補がある場合は、計装するライブラリの作者がウェブエンジンを選択することになります。例として、サーバーにmod_wsgiを使用したApache HTTP Server、WebフレームワークにDjangoを使用したPythonアプリケーションを見てみましょう。この状況では、 36 | 37 | 41 | 42 | * 計装の作成者の判断により、Apache HTTP Server または `mod_wsgi` のいずれかを `webengine` として選択しても構いません(MAY)。 43 | * Django は `webengine` に設定すべきではありません (SHOULD NOT) 。必要な情報はすでに計装のライブラリにあり、これを `webengine` に設定すると情報が重複してしまうからです。 44 | -------------------------------------------------------------------------------- /specification/specification/sdk-configuration.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # SDKのデフォルト設定 6 | 7 |
8 | 目次 9 | 10 | 11 | 15 | 16 | * [概要](#概要) 17 | * [設定インターフェース](#設定インターフェース) 18 | 19 | 20 |
21 | 22 | 25 | 26 | ## 概要 27 | 28 | 34 | 35 | デフォルトのOpen Telemetry SDK(以下、SDK)は高度な設定が可能です。本ドキュメントでは、SDKを設定するためのメカニズムの概要を説明しています。設定できる内容の詳細を規定するものではありません。 36 | 37 | 40 | 41 | ## 設定インターフェース 42 | 43 | 46 | 47 | ### プログラム的 48 | 49 | 54 | 55 | SDKは、すべての設定のためのプログラム的なインターフェースを提供しなければなりません(MUST)。このインターフェイスは、SDK自体の言語で書かれるべきです(SHOULD)。他のすべての設定メカニズムは、このインターフェースの上に構築されるべきです(SHOULD)。 56 | 57 | 63 | 64 | このプログラム・インターフェースの例として、SDKビルダー・クラスで定義された構造体を受け入れることが挙げられます。そこから、ファイル(YAML、JSON、TOMLなど)を受け取り、プログラム・インターフェースで消費可能な定義済みの構造体に変換するCLIを構築することができます。 65 | 66 | 67 | 70 | 71 | ### 他のメカニズム 72 | 73 | 78 | 79 | 追加の設定メカニズムは、SDKの言語に適した言語/フォーマット/スタイルで提供されるべきです(SHOULD)。SDKは適切な数の設定メカニズムを含むことができます。 80 | -------------------------------------------------------------------------------- /specification/specification/trace/sdk_exporters/non-otlp.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 非OTLPフォーマットへのOpenTelemetry変換 6 | 7 | 10 | 11 | **Status**: [Stable](../../document-status.md) 12 | 13 | 20 | 21 | すべてのOpenTelemetryコンセプトとOpenTelemetry APIを使って記録されたSpanデータは、OTLPフォーマットの対応するメッセージとフィールドを使って直接かつ正確に表現することができます。しかし、他のフォーマットについては、必ずしもそうではありません。あるフォーマットが、特定のOpenTelemetryコンセプトやコンセプトのフィールドを表現するネイティブな方法を持っていないこともあります。 22 | 23 | 28 | 29 | このドキュメントでは、OTLP以外のフォーマットとOpenTelemetryの間の変換を定義しています。OpenTelemetryのフィールドやコンセプトは、他のフォーマットでは直接の意味的な互換性がありません。 30 | 31 | 35 | 36 | 注:あるフォーマットが、特定のフィールドやコンセプトに対して意味的に等価なフィールド直接的に持っている場合、この文書の推奨事項は無視されなければなりません(MUST)。 37 | 38 | 43 | 44 | [Jaeger](jaeger.md)と[Zipkin](zipkin.md)の特定の変換ルールも追加で参照してください。JaegerとZipkinの固有のルールは、このドキュメントで定義された一般的なルールよりも優先されます。 45 | 46 | 49 | 50 | ## マッピング 51 | 52 | 55 | 56 | ### InstrumentationLibrary 57 | 58 | 62 | 63 | OpenTelemetry `InstrumentationLibrary` のフィールドは、以下のマッピングを使用して、Spanに関連付けられたキーと値のペアとして報告されなければなりません(MUST)。 64 | 65 | 71 | 72 | | OpenTelemetry InstrumentationLibrary フィールド | 非OTLPのキー | 73 | | ------------------- | --- | 74 | | `InstrumentationLibrary.name`|`otel.library.name`| 75 | | `InstrumentationLibrary.version`|`otel.library.version`| 76 | 77 | 80 | 81 | ### Span Status 82 | 83 | 87 | 88 | Spanの `Status` は、 `Status` が `UNSET` でない限り、Spanに関連付けられたキー・バリュー・ペアとして報告されなければなりません(MUST)。後者の場合は、報告してはいけません(MUST NOT)。 89 | 90 | 94 | 95 | 以下の表は、OpenTelemetryの`Status`とSpanのキーと値のペアのマッピングを定義しています。 96 | 97 | 103 | 104 | |OpenTelemetry Status フィールド|非OTLPのキー|非OTLPの値| 105 | |--|--|--| 106 | |Code | `otel.status_code` | このコードの名前は、`OK`または`ERROR`です。コードが `UNSET` の場合、設定してはいけません (MUST NOT) | 107 | |Description | `otel.status_description` | `Status`に値がある場合はその説明、ない場合は設定されていません | 108 | 109 | 112 | 113 | ### ドロップされた属性数 114 | 115 | 121 | 122 | OpenTelemetry Span のドロップされた属性数は、Span に関連付けられたキー・バリュー・ペアとして報告されなければなりません(MUST)。同様に、Spanイベントのドロップされた属性数は、Spanイベントに関連付けられたキー・バリュー・ペアとして報告されなければなりません(MUST)。どちらの場合も、キー名は `otel.dropped_attributes_count` としなければなりません(MUST)。 123 | 124 | 127 | 128 | このキー・バリュー・ペアは、ゼロ以外の値が含まれている場合にのみ記録されます。 129 | 130 | 133 | 134 | ### ドロップされた Events 数 135 | 136 | 140 | 141 | OpenTelemetry Spanのドロップされたイベント数は、Spanに関連付けられたキー・バリュー・ペアとして報告されなければなりません(MUST)。キーの名前は `otel.dropped_events_count` でなければなりません(MUST)。 142 | 143 | 146 | 147 | このキー・バリュー・ペアは、ゼロ以外の値が含まれている場合にのみ記録されます。 148 | 149 | -------------------------------------------------------------------------------- /specification/specification/trace/semantic_conventions/README.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # Trace セマンティック規約 6 | 7 | 10 | 11 | **Status**: [Experimental](../../document-status.md) 12 | 13 | 25 | 26 | OpenTelemetryでは、Spanは自由に作成することができ、表現される操作に特有の属性でSpanをアノテートするのは実装者の責任です。Spanは、システム内およびシステム間の特定の操作を表します。これらの操作の中には、HTTPやデータベースコールなどのよく知られたプロトコルを使用するコールを表すものがあります。プロトコルや操作の種類によっては、監視システムでSpanを正しく表現し、分析するための追加情報が必要になります。また、これらの属性を異なる言語で統一することも重要です。こうすることで、オペレータは言語の詳細を学ぶ必要がなくなり、ポリグロット(多言語)のマイクロサービス環境から収集されたテレメトリは、依然として容易に相関関係を保ち、相互に分析することができます。 27 | 28 | 31 | 32 | Spanのセマンティック規約は以下のように定義されています。 33 | 34 | 43 | 44 | * [General](span-general.md): 異なる種類の操作を記述する際に使用される可能性のある一般的なセマンティック属性 45 | * [HTTP](http.md): HTTPクライアントとサーバーのSpan 46 | * [Database](database.md): SQLとNoSQLのクライアントコールに対応したSpan 47 | * [RPC/RMI](rpc.md): リモートプロシージャコール(例:gRPC)のSpan 48 | * [Messaging](messaging.md): メッセージングシステム(キュー、パブリッシュ/サブスクライブなど)とのやりとりのためのSpan 49 | * [FaaS](faas.md): Function as a Service(例:AWS Lambda)のためのSpan 50 | * [Exceptions](exceptions.md): Spanに関連する例外を記録するための属性 51 | 52 | 55 | 56 | 以下のライブラリ固有のセマンティック規約が定義されています。 57 | 58 | 62 | 63 | * [AWS Lambda](instrumentation/aws-lambda.md): AWS Lambda 64 | * [AWS SDK](instrumentation/aws-sdk.md): AWS SDK 65 | 66 | 71 | 72 | Traceや[metricsのセマンティック規約](../../metrics/semantic_conventions/README.md)とは別に、OpenTelemetryは独自の[Resourceセマンティック規約](../../resource/sdk.md)を持つ包括的な[Resources]の概念も定義しています。 73 | -------------------------------------------------------------------------------- /specification/specification/trace/semantic_conventions/exceptions.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # 例外のセマンティック規約 6 | 7 | **Status**: [Experimental](../../document-status.md) 8 | 9 | 13 | 14 | このドキュメントでは、アプリケーションの例外を記録するためのセマンティック規約を定義しています。 15 | 16 | 17 | 18 | 23 | 24 | - [例外の記録](#例外の記録) 25 | - [属性](#属性) 26 | - [スタックトレースの表現](#スタックトレースの表現) 27 | 28 | 29 | 30 | 33 | 34 | ## 例外の記録 35 | 36 | 40 | 41 | 例外は、それが発生したSpan上の `イベント` として記録されるべきです (SHOULD)。イベントの名前は `"exception"` でなければなりません。 42 | 43 | 44 | 45 | 50 | 51 | APIで提供される[`recordException`メソッド](../api.md#record-exception)を使って、このセマンティック規約を実装した自動計装実装の典型的なテンプレートは、以下のようになります(擬似Java)。 52 | 53 | ```java 54 | Span span = myTracer.startSpan(/*...*/); 55 | try { 56 | // Code that does the actual work which the Span represents 57 | } catch (Throwable e) { 58 | span.recordException(e, Attributes.of("exception.escaped", true)); 59 | throw e; 60 | } finally { 61 | span.end(); 62 | } 63 | ``` 64 | 65 | 68 | 69 | ## 属性 70 | 71 | 75 | 76 | 以下の表は、`Event`に追加すべき属性とそのタイプを示しています。 77 | 78 | 79 | 80 | | Attribute | Type | Description | Examples | Required | 81 | |---|---|---|---|---| 82 | | `exception.type` | string | 例外のタイプ(該当する場合は、完全修飾クラス名)。例外の動的な型をサポートする言語では、静的型よりも動的型を優先すべきです。 | `java.net.ConnectException`; `OSError` | See below | 83 | | `exception.message` | string | 例外のメッセージ | `Division by zero`; `Can't convert 'int' object to str implicitly` | See below | 84 | | `exception.stacktrace` | string | スタックトレースは、言語ランタイムの自然な表現の文字列です。この表現は各言語のSIGが決定し、文書化することになっています。 | `Exception in thread "main" java.lang.RuntimeException: Test exception\n at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` | No | 85 | | `exception.escaped` | boolean | 例外がSpanの範囲を逸脱していることが分かっている場所で例外イベントが記録された場合、trueに設定するべきです(SHOULD)。 [1] | | No | 86 | 87 | **[1]:** 例外が論理的に"飛行中(in flight)"である間にSpanが終了した場合、例外はSpanの範囲から脱出(または離脱)したとみなされます。これは、言語によっては実際に"飛行中"かもしれませんが(例:Pythonで例外がContext managerの`__exit__`メソッドに渡された場合)、ほとんどの言語では例外を記録した時点で捕捉されるのが普通です。 88 | 例外が投げられた時点で、その例外がSpanのスコープから外れるかどうかを判断することは通常できません。しかし、[上記の例](#exception-end-example)のように、Spanを終了する直前にアクティブな例外があるかどうかをチェックすれば、例外がエスケープされるかどうかを知ることは簡単です。 89 | これによると、`exception.escaped` 属性が設定されていなかったり、false に設定されていたりしても、例外がSpanのスコープを抜け出す可能性があります。これは、例外が抜け出すかどうかがはっきりしない時点でイベントが記録されている可能性があるからです。 90 | 91 | **Additional attribute requirements:** At least one of the following sets of attributes is required: 92 | 93 | * `exception.type` 94 | * `exception.message` 95 | 96 | 97 | 100 | 101 | ### スタックトレースの表現 102 | 103 | 109 | 110 | 以下の表は、[Google Cloud][gcp-error-reporting]からの引用で、様々な言語でのスタックトレースの表現を含んでいます。この表は、特定の言語を推奨するものではありませんが、SIGが適切と判断した場合には自由に採用することができます． 111 | 112 | 122 | 123 | | 言語 | Format | 124 | | ---------- | ------------------------------------------------------------------- | 125 | | C# | [Exception.ToString()][csharp-stacktrace]の戻り値 | 126 | | Go | [runtime.Stack][go-stacktrace]の戻り値 | 127 | | Java | [Throwable.printStackTrace()][java-stacktrace]の内容 | 128 | | Javascript | V8で返される[error.stack][js-stacktrace]の戻り値 | 129 | | Python | [traceback.format_exc()][python-stacktrace]の戻り値 | 130 | | Ruby | [Exception.full_message][ruby-full-message]の戻り値 | 131 | 132 | 138 | 139 | バックエンドは、必要に応じてStacktraceからより詳細な情報を抽出するために、[telemetry sdk resource][telemetry-sdk-resource]からのプラットフォーム情報と組み合わせて、スタックトレースを生成するために言語で指定された方法を使用することができます。 140 | 141 | 151 | 152 | [gcp-error-reporting]: https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report 153 | [java-stacktrace]: https://docs.oracle.com/javase/7/docs/api/java/lang/Throwable.html#printStackTrace%28%29 154 | [python-stacktrace]: https://docs.python.org/3/library/traceback.html#traceback.format_exc 155 | [js-stacktrace]: https://v8.dev/docs/stack-trace-api 156 | [ruby-full-message]: https://ruby-doc.org/core-2.7.1/Exception.html#method-i-full_message 157 | [csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring 158 | [go-stacktrace]: https://golang.org/pkg/runtime/debug/#Stack 159 | [telemetry-sdk-resource]:../../resource/semantic_conventions/README.md#telemetry-sdk 160 | -------------------------------------------------------------------------------- /specification/specification/vendors.md: -------------------------------------------------------------------------------- 1 | 4 | 5 | # ベンダー 6 | 7 |
8 | 目次 9 | 10 | 16 | 17 | * [概要](#概要) 18 | * [Supports OpenTelemetry](#supports-opentelemetry) 19 | * [Implements OpenTelemetry](#implements-opentelemetry) 20 | * [資格](#資格) 21 | 22 | 23 |
24 | 25 | 28 | 29 | ## 概要 30 | 31 | 43 | 44 | OpenTelemetryプロジェクトは、API、SDK、プロトコル、セマンティックな規約の[仕様書](https://github.com/open-telemetry/opentelemetry-specification)と、いくつかの言語のためのそれぞれの実装の両方から構成されています。デフォルトのSDKの実装は、[高度な設定が可能](sdk-configuration.md)で拡張可能であり、例えば[Span Processor](trace/sdk.md#span-processor)を介して、特定のベンダーが必要とする追加ロジックを、カスタムSDKを実装することなく追加することができます。カスタムSDKを必要としないということは、ほとんどの言語において、ユーザーはすでに使用する実装を見つけることができ、もしそうでない場合は、新しい言語で実装するための十分に文書化された仕様に従うことができるということです。 45 | 46 | 51 | 52 | その目的は、ユーザーがベンダーを簡単に切り替えられるようにすることと、OpenTelemetry SDKを実装した言語が、OpenTelemetryのサポートを表明しているどのベンダーでも動作することを保証することです。 53 | 54 | 58 | 59 | このドキュメントでは、ベンダーが「OpenTelemetryをサポート(Supports OpenTelemetry)」または「OpenTelemetryを実装(Implements OpenTelemetry)」しているとみなされるために必要なことを説明します。 60 | 61 | 64 | 65 | ## Supports OpenTelemetry 66 | 67 | 71 | 72 | "Supports OpenTelemetry"とは、ベンダーが2つのメカニズムのうちの1つを通して、デフォルトのSDKの出力を受け入れる必要があることを意味します: 73 | 74 | 78 | 79 | - [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector/)および/またはOpenTelemetry SDK用のエクスポーターを提供する方法 80 | - [OpenTelemetryプロトコル](https://github.com/open-telemetry/opentelemetry-proto)用のレシーバーを構築する方法 81 | 82 | 83 | 86 | 87 | ## Implements OpenTelemetry 88 | 89 | 94 | 95 | カスタムSDKを実装しているベンダーは「Implements OpenTelemetry」と表示されます。カスタムSDKが任意である場合、そのベンダーは「Supports OpenTelemetry」と表示されます。 96 | 97 | 100 | 101 | ## 資格 102 | 103 | 110 | 111 | ベンダーは、サポートしているテレメトリの種類でOpenTelemetryのサポートという資格を得ることができます。例えば、OpenTelemetryプロトコルのエクスポートをメトリックのみで受け入れているベンダーは「Supports OpenTelemetry Metrics」と表示され、トレーシングのためだけにカスタムSDKを実装しているベンダーは「Implements OpenTelemetry Tracing」と表示されます。 112 | 113 | --------------------------------------------------------------------------------