From fcc47d82be2d843ff8087cb98c4eff8f06026677 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Tue, 23 Jul 2024 14:48:25 +0200 Subject: [PATCH 01/13] Introduce component owners (#4646) --- .github/CODEOWNERS | 37 ------------ .github/component-owners.yml | 79 ++++++++++++++++++++++++++ .github/workflows/component-owners.yml | 13 +++++ 3 files changed, 92 insertions(+), 37 deletions(-) create mode 100644 .github/component-owners.yml create mode 100644 .github/workflows/component-owners.yml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 6b090dbe7bc3..f61d9e7aba30 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -14,40 +14,3 @@ # Global owners, will be the owners for everything in the repo. * @open-telemetry/docs-approvers - -# content owners -content-modules/ @open-telemetry/docs-maintainers -content-modules/opamp-spec @open-telemetry/docs-maintainers @open-telemetry/opamp-spec-approvers -content-modules/opentelemetry-proto @open-telemetry/docs-maintainers @open-telemetry/specs-approvers -content-modules/opentelemetry-specification @open-telemetry/docs-maintainers @open-telemetry/specs-approvers -content-modules/semantic-conventions @open-telemetry/docs-maintainers @open-telemetry/specs-semconv-approvers -content/en/blog/ @open-telemetry/docs-maintainers -content/en/community/end-user/ @open-telemetry/docs-approvers @open-telemetry/sig-end-user-approvers -content/en/docs/collector @open-telemetry/docs-approvers @open-telemetry/collector-approvers -content/en/docs/contributing/ @open-telemetry/docs-approvers @open-telemetry/docs-maintainers -content/en/docs/demo @open-telemetry/docs-approvers @open-telemetry/demo-approvers -content/en/docs/kubernetes/helm/ @open-telemetry/docs-approvers @open-telemetry/helm-approvers -content/en/docs/kubernetes/operator/ @open-telemetry/docs-approvers @open-telemetry/operator-approvers -content/en/docs/languages/cpp/ @open-telemetry/docs-approvers @open-telemetry/cpp-approvers -content/en/docs/languages/erlang/ @open-telemetry/docs-approvers @open-telemetry/erlang-approvers -content/en/docs/languages/go/ @open-telemetry/docs-approvers @open-telemetry/go-approvers @open-telemetry/go-instrumentation-approvers -content/en/docs/languages/java/ @open-telemetry/docs-approvers @open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers -content/en/docs/languages/js/ @open-telemetry/docs-approvers @open-telemetry/javascript-approvers -content/en/docs/languages/net/ @open-telemetry/docs-approvers @open-telemetry/dotnet-approvers @open-telemetry/dotnet-instrumentation-approvers -content/en/docs/languages/php/ @open-telemetry/docs-approvers @open-telemetry/php-approvers -content/en/docs/languages/python/ @open-telemetry/docs-approvers @open-telemetry/python-approvers -content/en/docs/languages/ruby/ @open-telemetry/docs-approvers @open-telemetry/ruby-approvers @open-telemetry/ruby-contrib-approvers -content/en/docs/languages/rust/ @open-telemetry/docs-approvers @open-telemetry/rust-approvers -content/en/docs/languages/swift/ @open-telemetry/docs-approvers @open-telemetry/swift-approvers -content/en/docs/security/ @open-telemetry/docs-approvers @open-telemetry/sig-security-maintainers -content/en/docs/specs/ @open-telemetry/docs-approvers @open-telemetry/specs-approvers -content/en/docs/zero-code/go @open-telemetry/docs-approvers @open-telemetry/go-approvers @open-telemetry/go-instrumentation-approvers -content/en/docs/zero-code/java/ @open-telemetry/docs-approvers @open-telemetry/java-approvers @open-telemetry/java-instrumentation-approvers -content/en/docs/zero-code/js/ @open-telemetry/docs-approvers @open-telemetry/javascript-approvers -content/en/docs/zero-code/net/ @open-telemetry/docs-approvers @open-telemetry/dotnet-approvers @open-telemetry/dotnet-instrumentation-approvers -content/en/docs/zero-code/python/ @open-telemetry/docs-approvers @open-telemetry/python-approvers -content/en/docs/zero-code/php/ @open-telemetry/docs-approvers @open-telemetry/php-approvers -content/en/ecosystem/demo/ @open-telemetry/demo-approvers @open-telemetry/demo-approvers -content/zh/ @open-telemetry/docs-maintainers @open-telemetry/docs-zh-approvers -content/ja/ @open-telemetry/docs-maintainers @open-telemetry/docs-ja-approvers - diff --git a/.github/component-owners.yml b/.github/component-owners.yml new file mode 100644 index 000000000000..f92ed31dbe18 --- /dev/null +++ b/.github/component-owners.yml @@ -0,0 +1,79 @@ +# This file is used to define the owners of the content modules in the OpenTelemetry repository. +components: + content-modules: + - open-telemetry/docs-maintainers + content-modules/opamp-spec: + - open-telemetry/docs-maintainers + - open-telemetry/opamp-spec-approvers + content-modules/opentelemetry-proto: + - open-telemetry/docs-maintainers + - open-telemetry/specs-approvers + content-modules/opentelemetry-specification: + - open-telemetry/docs-maintainers + - open-telemetry/specs-approvers + content-modules/semantic-conventions: + - open-telemetry/docs-maintainers + - open-telemetry/specs-semconv-approvers + content/en/blog: + - open-telemetry/docs-maintainers + content/en/community/end-user: + - open-telemetry/sig-end-user-approvers + content/en/docs/collector: + - open-telemetry/collector-approvers + content/en/docs/contributing: + - open-telemetry/docs-maintainers + content/en/docs/demo: + - open-telemetry/demo-approvers + content/en/docs/kubernetes/helm: + - open-telemetry/helm-approvers + content/en/docs/kubernetes/operator: + - open-telemetry/operator-approvers + content/en/docs/languages/cpp: + - open-telemetry/cpp-approvers + content/en/docs/languages/erlang: + - open-telemetry/erlang-approvers + content/en/docs/languages/go: + - open-telemetry/go-approvers + - open-telemetry/go-instrumentation-approvers + content/en/docs/languages/java: + - open-telemetry/java-approvers + - open-telemetry/java-instrumentation-approvers + content/en/docs/languages/js: + - open-telemetry/javascript-approvers + content/en/docs/languages/net: + - open-telemetry/dotnet-approvers + - open-telemetry/dotnet-instrumentation-approvers + content/en/docs/languages/php: + - open-telemetry/php-approvers + content/en/docs/languages/python: + - open-telemetry/python-approvers + content/en/docs/languages/ruby: + - open-telemetry/ruby-approvers + - open-telemetry/ruby-contrib-approvers + content/en/docs/languages/rust: + - open-telemetry/rust-approvers + content/en/docs/languages/swift: + - open-telemetry/swift-approvers + content/en/docs/security: + - open-telemetry/sig-security-maintainers + content/en/docs/specs: + - open-telemetry/specs-approvers + content/en/docs/zero-code/java: + - open-telemetry/java-approvers + - open-telemetry/java-instrumentation-approvers + content/en/docs/zero-code/js: + - open-telemetry/javascript-approvers + content/en/docs/zero-code/net: + - open-telemetry/dotnet-approvers + - open-telemetry/dotnet-instrumentation-approvers + content/en/ecosystem/demo: + - open-telemetry/demo-approvers + content/zh: + - open-telemetry/docs-maintainers + - open-telemetry/docs-zh-approvers + content/ja: + - open-telemetry/docs-maintainers + - open-telemetry/docs-ja-approvers + content/pt: + - open-telemetry/docs-maintainers + - open-telemetry/docs-pt-approvers diff --git a/.github/workflows/component-owners.yml b/.github/workflows/component-owners.yml new file mode 100644 index 000000000000..5429dc4ae505 --- /dev/null +++ b/.github/workflows/component-owners.yml @@ -0,0 +1,13 @@ +name: Component owners +on: + pull_request_target: + +jobs: + run_self: + runs-on: ubuntu-latest + name: Assign component owners + steps: + - uses: dyladan/component-owners@v0.1.0 + with: + config-file: .github/component-owners.yml + repo-token: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }} From a2c88f5ab300bb14bcd4d95ad6805d5c64929323 Mon Sep 17 00:00:00 2001 From: Yoshi Yamaguchi Date: Wed, 24 Jul 2024 03:04:54 +0900 Subject: [PATCH 02/13] [ja] Japanese translation of instrumentation (#4809) Co-authored-by: Severin Neumann --- .../docs/concepts/instrumentation/_index.md | 35 ++ .../concepts/instrumentation/code-based.md | 49 +++ .../concepts/instrumentation/libraries.md | 354 ++++++++++++++++++ .../concepts/instrumentation/zero-code.md | 39 ++ 4 files changed, 477 insertions(+) create mode 100644 content/ja/docs/concepts/instrumentation/_index.md create mode 100644 content/ja/docs/concepts/instrumentation/code-based.md create mode 100644 content/ja/docs/concepts/instrumentation/libraries.md create mode 100644 content/ja/docs/concepts/instrumentation/zero-code.md diff --git a/content/ja/docs/concepts/instrumentation/_index.md b/content/ja/docs/concepts/instrumentation/_index.md new file mode 100644 index 000000000000..996fda38b25c --- /dev/null +++ b/content/ja/docs/concepts/instrumentation/_index.md @@ -0,0 +1,35 @@ +--- +title: 計装 +description: OpenTelemetryはどのように計装を促進するか +weight: 15 +default_lang_commit: d8c5612 +--- + +システムを観測可能にするためには、システムが **計装** されなければなりません。 +つまり、システムコンポーネントのコードが[トレース](/docs/concepts/signals/traces/)、[メトリクス](/docs/concepts/signals/metrics/)、[ログ](/docs/concepts/signals/logs/)といったテレメトリーシグナルを送出しなければなりません。 + +OpenTelemetry を使えば、主に2つの方法でコードを計装できます。 + +1. 公式の[各言語向けのAPIとSDK](/docs/languages/)を使った[コードベースソリューション](/docs/concepts/instrumentation/code-based) +2. [ゼロコードソリューション](/docs/concepts/instrumentation/zero-code/) + +**コードベース** ソリューションは、より深い洞察とリッチなテレメトリーをアプリケーション自身から得ることを可能にします。 +OpenTelemetry APIを使ってアプリケーションからテレメトリーを生成でき、ゼロコードソリューションによって生成されたテレメトリーを補完する重要な役割を果たします。 + +**ゼロコード** ソリューションは、テレメトリーの取得を初めて行うときや、テレメトリーを取得する必要のあるアプリケーションを修正できない時に最適です。 +それらは、あなたが使用しているライブラリや、アプリケーションが動作している環境から、豊富なテレメトリーを提供します。 +別の考え方をすれば、アプリケーションの _エッジで_ 何が起こっているかについての情報を提供する、ということです。 + +両方のソリューションを同時に使うこともできます。 + +## OpenTelemetryのその他の利点 {#additional-opentelemetry-benefits} + +OpenTelemetryが提供するのは、ゼロコードやコードベースのテレメトリーソリューションだけではありません。 +以下のものもOpenTelemetryの一部です。 + +- ライブラリは依存関係として OpenTelemetry API を活用することができ、OpenTelemetry SDK がインポートされない限り、そのライブラリを使用するアプリケーションに影響はありません。 +- それぞれの[シグナル](/docs/concepts/signals)(トレース、メトリクス、ログ)に対して、それらを作成、処理、エクスポートするためのいくつかの方法が用意されています。 +- [コンテキスト伝播](/docs/concepts/context-propagation)が実装に組み込まれているので、シグナルがどこで生成されたかに関係なく、シグナルを相関させられます。 +- [リソース](/docs/concepts/resources)と[計装スコープ](/docs/concepts/instrumentation-scope)は、[ホスト](/docs/specs/semconv/resource/host/)、[オペレーティングシステム](/docs/specs/semconv/resource/os/)、[Kubernetesクラスター](/docs/specs/semconv/resource/k8s/#cluster)のように、異なるエンティティごとにシグナルをグループ化できます。 +- APIとSDKの各言語固有の実装は、[OpenTelemetry仕様](/docs/specs/otel/)の要件と期待に従います。 +- [セマンティック規約](/docs/concepts/semantic-conventions)は、コードベースやプラットフォーム間で標準化のために使用できる共通の命名スキーマを提供します。 diff --git a/content/ja/docs/concepts/instrumentation/code-based.md b/content/ja/docs/concepts/instrumentation/code-based.md new file mode 100644 index 000000000000..a79ffdbb3485 --- /dev/null +++ b/content/ja/docs/concepts/instrumentation/code-based.md @@ -0,0 +1,49 @@ +--- +title: コードベース +description: コードベース計装のセットアップに不可欠なステップを学ぶ +weight: 20 +cSpell:ignore: proxying +default_lang_commit: d8c5612 +--- + +## OpenTelemetry APIとSDKをインポートする {#import-the-opentelemetry-api-and-sdk} + +まず、あなたのサービスコードに OpenTelemetry をインポートする必要があります。 +もし、実行可能なバイナリによって消費されることを意図したライブラリやその他のコンポーネントを開発しているのであれば、APIにだけ依存することになるでしょう。 +アーティファクトがスタンドアロンのプロセスやサービスであれば、APIとSDKに依存することになります。 +OpenTelemetry APIとSDKの詳細については、[仕様](/docs/specs/otel/)を参照してください。 + +## OpenTelemetry API を設定する {#configure-the-opentelemetry-api} + +トレースやメトリクスを作成するには、まずトレーサーやメーターのプロバイダーを作成する必要があります。 +一般的に、SDKはこれらのオブジェクトに対して単一のデフォルトプロバイダーを提供することを推奨します。 +次に、そのプロバイダーからトレーサーまたはメーターのインスタンスを取得し、名前とバージョンを与えます。 +たとえばライブラリを書いているのであれば、ライブラリの名前（たとえば `com.example.myLibrary`）を付けるべきです。 +また、ライブラリやサービスの現在のバージョンに対応するバージョン文字列（例：`semver:1.0.0`）を指定することを推奨します。 + +## OpenTelemetry SDK を設定する {#configure-the-opentelemetry-sdk} + +サービスプロセスを構築している場合、テレメトリーデータを解析バックエンドにエクスポートするための適切なオプションをSDKに設定する必要もあります。 +この設定は、設定ファイルまたはその他のメカニズムを通じてプログラムで処理することを推奨します。 +また、場合によっては使いたくなるであろう、言語ごとのチューニングオプションもあります。 + +## テレメトリーデータの作成 {#create-telemetry-data} + +APIとSDKを設定したら、プロバイダーから取得したトレーサーオブジェクトとメーターオブジェクトを通して、トレースとメトリックイベントを自由に作成できるようになります。 +依存関係のために計装ライブラリを利用しましょう。これらの詳細については、[レジストリ](/ecosystem/registry/) やあなたの言語のレポジトリをチェックしてください。 + +## データのエクスポート {#export-data} + +テレメトリーデータを作成したら、それをどこかに送信したいでしょう。 +OpenTelemetryは、プロセスから分析バックエンドにデータをエクスポートする2つの主要な方法をサポートしています。 +プロセスから直接エクスポートするか、[OpenTelemetryコレクター](/docs/collector)を通してプロキシする方法です。 + +プロセス内からのエクスポートでは、1つ以上の _エクスポーター_ をインポートして依存する必要があります。 +エクスポーターとは、OpenTelemetry のメモリ内のスパンやメトリクスオブジェクトを、JaegerやPrometheusのようなテレメトリー分析ツールに適したフォーマットに変換するライブラリです。 +さらに、OpenTelemetry は `OTLP` として知られるワイヤプロトコルをサポートしていて、これはすべての OpenTelemetry SDK でサポートされています。 +このプロトコルは、OpenTelemetryコレクターにデータを送るために使用できます。 +OpenTelemetryコレクターはスタンドアローンのバイナリプロセスで、サービスインスタンスのプロキシやサイドカーとして実行したり、別のホストで実行したりできます。 +コレクターは、このデータを転送し、好きな分析ツールにエクスポートするように設定できます。 + +JaegerやPrometheusのようなオープンソースツールに加えて、OpenTelemetryからのテレメトリデータの取り込みをサポートする企業のリストが増えています。 +詳細は、[ベンダー](/ecosystem/vendors/)のページを参照してください。 diff --git a/content/ja/docs/concepts/instrumentation/libraries.md b/content/ja/docs/concepts/instrumentation/libraries.md new file mode 100644 index 000000000000..e7c89111f324 --- /dev/null +++ b/content/ja/docs/concepts/instrumentation/libraries.md @@ -0,0 +1,354 @@ +--- +title: ライブラリ +description: ライブラリにネイティブ計装を追加する方法を紹介します。 +weight: 40 +default_lang_commit: d8c5612 +--- + +OpenTelemetryは、多くのライブラリに[計装ライブラリ][instrumentation libraries]を提供していて、これは通常、ライブラリフックやモンキーパッチライブラリコードを通して行われます。 + +OpenTelemetry を使ったネイティブのライブラリ計装は、ユーザにより良いオブザーバビリティと開発者体験を提供し、ライブラリがフックを公開して、ドキュメントを書く必要性を取り除きます。 + +- カスタムロギングフックは、一般的で使いやすいOpenTelemetry APIに置き換えられ、ユーザーはOpenTelemetryとだけやり取りすることになります。 +- ライブラリとアプリケーションコードからのトレース、ログ、メトリクスを相関させ、一貫性を持たせられます。 +- 共通規約により、ユーザーは同じ技術内、ライブラリや言語間で類似した一貫性のあるテレメトリーを得られます。 +- テレメトリーシグナルは、さまざまな消費シナリオのために、十分にドキュメントが用意された多種多様なOpenTelemetry拡張ポイントを使用して、微調整（フィルター、処理、集約）できます。 + +## セマンティック規約 {#semantic-conventions} + +ウェブフレームワーク、RPCクライアント、データベース、メッセージングクライアント、インフラなどをカバーする利用可能な[セマンティック規約](/docs/specs/semconv/general/trace/)をチェックしてください！ + +もしあなたのライブラリがそのようなものであるなら、規約にしたがってください。 +規約は主要な情報源であり、どの情報がスパンに含まれるべきかを教えてくれます。 +規約は、計装に一貫性を持たせます。テレメトリーに携わるユーザーは、ライブラリの仕様を学ぶ必要がありませんし、オブザーバビリティベンダーは、さまざまなテクノロジー（たとえば、データベースやメッセージングシステム）に対応した体験を構築できます。 +ライブラリが規約にしたがえば、ユーザーの入力や設定なしで、多くのシナリオがそのまま有効になります。 + +セマンティック規約は常に進化しており、常に新しいものが追加されています。 +もしあなたのライブラリにないものがあれば、[追加する](https://github.com/open-telemetry/semantic-conventions/issues)ことを検討してください。 +スパン名には特に注意してください。 +意味のある名前を使うように努め、定義する際にはカーディナリティを考慮してください。 + +[`schema_url`]（/docs/specs/otel/schemas/#schema-url）属性があり、どのバージョンのセマンティック規約が使用されているかを記録できます。 +可能であれば、この属性を設定してください。 + +何かフィードバックがあったり、新しい規約を追加したい場合は、ぜひ貢献してください！ +CNCFのOpenTelemetryに関する[計装チャンネル（ `#otel-instrumentation` ）](https://cloud-native.slack.com/archives/C01QZFGMLQ7)や[仕様のレポジトリ](https://github.com/open-telemetry/opentelemetry-specification)から始めるとよいでしょう！ + +### スパンの定義 {#defining-spans} + +ライブラリの利用者の視点からライブラリのことを考え、利用者がライブラリの動作やアクティビティについて何を知りたいと思うかを考えてみてください。 +ライブラリのメンテナーであるあなたは内部構造を知っていますが、ユーザーはライブラリの内部構造にはあまり興味を持たず、自分のアプリケーションの機能に興味を持つでしょう。 +ライブラリの使用状況を分析する上でどのような情報が役に立つかを考え、そのデータをモデル化する適切な方法を考えましょう。 +考慮すべき点は以下の通りです。 + +- スパンとスパンの階層 +- スパンの数値属性（集約されたメトリクスの代替として） +- スパンイベント +- 集約された指標 + +たとえば、ライブラリがデータベースへのリクエストを行っている場合、データベースへの論理的なリクエストに対してのみスパンを作成します。 +ネットワークを介した物理的なリクエストは、その機能を実装するライブラリ内で計装する必要があります。 +また、オブジェクトやデータのシリアライズのような他のアクティビティは、追加スパンとしてではなく、スパンイベントとして捕捉することをおすすめします。 + +スパン属性を設定するときは、セマンティック規約にしたがってください。 + +## 計装すべき**でない**とき {#when-not-to-instrument} + +いくつかのライブラリは、ネットワーク呼び出しをラップするシンクライアントです。 +OpenTelemetryに、RPCクライアント用の計装ライブラリがある可能性があります（[レジストリ](/ecosystem/registry/)をチェックしてください）。 +この場合、ラッパーライブラリの計装は必要ないかもしれません。 +一般的なガイドラインとして、ライブラリの計装は、そのライブラリ自身のレベルでのみ行ってください。 + +次のような場合は計装しないでください。 + +- あなたのライブラリは、ドキュメント化された、あるいは自明なAPIの上にある薄いプロキシです +- _そして_ OpenTelemetryのエコシステムに、土台となるネットワーク呼び出しの計装があります +- _そして_ テレメトリーを充実させるために、ライブラリがしたがうべき規約がありません + +迷ったら、計装はやめましょう。後で必要性を感じたときにいつでもできます。 + +もし、計装しないことを選択した場合でも、内部のRPCクライアントインスタンスに OpenTelemetryハンドラーを設定する方法を提供することは有用でしょう。 +これは、完全な自動計装をサポートしていない言語では必須ですが、その他の言語でも有用です。 + +この文書の残りの部分では、計装を行うことを決定した場合、何をどのように計装するのかについて手引きを示します。 + +## OpenTelemetry API {#opentelemetry-api} + +最初のステップは、OpenTelemetry APIパッケージへ依存することです。 + +OpenTelemetryには[2つの主要なモジュール](/docs/specs/otel/overview/)であるAPIとSDKがあります。 +OpenTelemetry API は、抽象化と動作しない実装のセットです。 +アプリケーションが OpenTelemetry SDKをインポートしない限り、あなたの計装は何もせず、アプリケーションのパフォーマンスに影響を与えません。 + +**ライブラリはOpenTelemetry APIのみを使用すべきです。** + +新しい依存関係を追加することを心配するのは当然かもしれませんが、依存地獄を最小限に抑える方法を決めるのに役立ついくつかの考慮事項を紹介しましょう。 + +- OpenTelemetry Trace APIは2021年初めに安定版に達しました。このAPIは[Semantic Versioning 2.0](/docs/specs/otel/versioning-and-stability/)にしがたっていて、開発チームはAPIの安定性を真剣に受け止めています。 +- 依存する場合は、もっとも早い安定版の OpenTelemetry API (1.0.\*)を使用し、新機能を使用する必要がない限り、アップデートは避けてください。 +- あなたの計装が安定するまでの間、それを別のパッケージとしてリリースすることを検討してください。 + あなたのレポジトリに置いておくこともできますし、[OpenTelemetryに追加](https://github.com/open-telemetry/oteps/blob/main/text/0155-external-modules.md#contrib-components) して、他の計装パッケージと一緒にリリースすることもできます。 +- セマンティック規約は[安定していますが、徐々に発展しています][stable, but subject to evolution]。 + 機能的な問題は発生しませんが、ときどき、計装をアップデートする必要があるかもしれません。 + プレビュープラグインか、OpenTelemetry contrib リポジトリにそれを置くことで、ユーザの変更を壊すことなく、規約を最新に保つことができるかもしれません。 + + [stable, but subject to evolution]: /docs/specs/otel/versioning-and-stability/#semantic-conventions-stability + +### トレーサーを取得する {#getting-a-tracer} + +すべてのアプリケーションの設定は、Tracer API を通してライブラリから隠蔽されます。 +ライブラリは、アプリケーションに `TracerProvider` のインスタンスを渡して依存性注入とテストの容易さを促進したり、[グローバルの `TracerProvider`](/docs/specs/otel/trace/api/#get-a-tracer) から取得したりできます。 +OpenTelemetry 言語の実装は、インスタンスの受け渡しやグローバルへのアクセスについて、慣用的なものに基づいて好みが異なるかもしれません。 + +トレーサーを入手する際、ライブラリ（またはトレーシングプラグイン）の名前とバージョンを指定してください。 +これらはテレメトリーに表示され、ユーザーがテレメトリーを処理してフィルタリングし、それがどこから来たのかを理解し、計装の問題をデバッグ／報告するのに役立ちます。 + +## 何を計装すべきか {#what-to-instrument} + +### パブリックAPI {#public-apis} + +パブリックAPI呼び出し用に作成されたスパンによって、ユーザーはテレメトリーをアプリケーションコードにマッピングし、ライブラリ呼び出しの期間と結果を理解できます。 +トレースすべき呼び出しは次のとおりです。 + +- 内部でネットワークコールを行うパブリックメソッドや、時間がかかり失敗する可能性のあるローカル操作（IOなど） +- リクエストやメッセージを処理するハンドラー + +**計装の例：** + +```java +private static Tracer tracer = getTracer(TracerProvider.noop()); + +public static void setTracerProvider(TracerProvider tracerProvider) { + tracer = getTracer(tracerProvider); +} + +private static Tracer getTracer(TracerProvider tracerProvider) { + return tracerProvider.getTracer("demo-db-client", "0.1.0-beta1"); +} + +private Response selectWithTracing(Query query) { + // スパンの名前と属性に関する手引きについては、規約をチェックすること + Span span = tracer.spanBuilder(String.format("SELECT %s.%s", dbName, collectionName)) + .setSpanKind(SpanKind.CLIENT) + .setAttribute("db.name", dbName) + ... + .startSpan(); + + // スパンをアクティブにし、ログとネストスパンの関連付けを可能にする + try (Scope unused = span.makeCurrent()) { + Response response = query.runWithRetries(); + if (response.isSuccessful()) { + span.setStatus(StatusCode.OK); + } + + if (span.isRecording()) { + // レスポンスコードやその他の情報をレスポンス属性に入力する + } + } catch (Exception e) { + span.recordException(e); + span.setStatus(StatusCode.ERROR, e.getClass().getSimpleName()); + throw e; + } finally { + span.end(); + } +} +``` + +属性を入力するための規約に従ってください！ +該当するものがない場合は、[一般的な規約](/docs/specs/semconv/general/attributes/)をチェックしてください。 + +### ネストされたネットワークとその他のスパン {#nested-network-and-other-spans} + +ネットワーク呼び出しは通常、対応するクライアントの実装を通して、OpenTelemetry 自動計装でトレースされます。 + +![JaegerのUIでのネストされたデータベースとHTTPスパン](../nested-spans.svg) + +OpenTelemetryがネットワーククライアントのトレースをサポートしていない場合、最善の判断をしてください。 + +- ネットワーク呼び出しをトレースすることで、ユーザーやあなたのサポート能力が向上するでしょうか +- あなたのライブラリは、公開され、ドキュメント化されたRPC API上のラッパーですか。問題が発生した場合、ユーザーは基礎となるサービスからサポートを受ける必要がありますか。 + - ライブラリーを計装し、個々のネットワークトライをトレースしましょう。 +- スパンを使ってこれらの呼び出しをトレースすると、非常に冗長になりますか、それともパフォーマンスに顕著な影響を与えますか。 + - 冗長性やスパンイベントにはログを使いましょう。ログは親（パブリックAPIコール）に関連付けられ、スパンイベントはパブリックAPIスパンに設定されるべきです。 + - スパンである必要がある場合（ユニークなトレースコンテキストを伝送し、伝播するため）、設定オプションで指定するようにさせ、デフォルトでは無効にしましょう。 + +OpenTelemetryがすでにネットワーク呼び出しのトレースをサポートしているのであれば、おそらく、それを複製する必要はないでしょう。 +以下のように例外もあります。 + +- 自動計装を使用しないユーザーをサポートする場合（環境によっては機能しない場合や、ユーザーがモンキーパッチに懸念を持つ場合がある） +- 基礎となるサービスとのカスタム（レガシー）相関およびコンテキスト伝播プロトコルを有効にする場合 +- 自動計装ではカバーされない、絶対に必要なライブラリ／サービス固有の情報でRPCスパンを充実させる場合 + +警告：重複を避けるための一般的なソリューションは現在作成中です 🚧 + +### イベント {#events} + +トレースは、アプリが発するシグナルの一種です。 +イベント（またはログ）とトレースは、互いに補完し合うものであり、重複するものではありません。 +冗長性を持たせる必要がある場合は、トレースよりもログの方が適しています。 + +あなたのアプリは、すでにロギングか、似たようなモジュールを使っている可能性があります。 +あなたのモジュールは、すでに OpenTelemetry と統合されているかもしれません。それを調べるには、[レジストリ](/ecosystem/registry/) を参照してください。 +統合は通常、すべてのログにアクティブなトレースコンテキストを埋め込むことで、ユーザがそれらを関連付けられるようになります。 + +あなたの言語とエコシステムが共通のロギングサポートを持っていない場合、[スパンイベント][span events]を使って追加のアプリの詳細を共有します。 +属性も追加したい場合は、イベントの方が便利かもしれません。 + +経験則として、詳細データにはスパンではなくイベントまたはログを使用しましょう。 +常に、計装が作成したスパンインスタンスにイベントを添付してください。 +アクティブスパンの使用は、それが何を参照しているのか制御できないため、できる限り避けてください。 + +## コンテキスト伝搬 {#context-propagation} + +### コンテキストの抽出 {#extracting-context} + +もしあなたがライブラリやサービス、たとえばウェブフレームワークやメッセージングコンシューマーなどの上流の呼び出しを受信するような仕事をしているなら、受信するリクエスト／メッセージからコンテキストを抽出する必要があります。 +OpenTelemetryは `Propagator` APIを提供していて、これは特定の伝播基準を隠して、トレースされた `Context` をワイヤーから読み取ります。 +単一のレスポンスの場合、ワイヤー上のコンテキストは1つだけです。これはライブラリが作成する新しいスパンの親になります。 + +スパンを作成した後、スパンをアクティブにすることで、新しいトレースコンテキストをアプリケーションコード（コールバックまたはハンドラー）に渡す必要があります。 + +```java +// コンテキストを抽出する +Context extractedContext = propagator.extract(Context.current(), httpExchange, getter); +Span span = tracer.spanBuilder("receive") + .setSpanKind(SpanKind.SERVER) + .setParent(extractedContext) + .startSpan(); + +// スパンをアクティブにし、ネストされたテレメトリーが相関するようにする +try (Scope unused = span.makeCurrent()) { + userCode(); +} catch (Exception e) { + span.recordException(e); + span.setStatus(StatusCode.ERROR); + throw e; +} finally { + span.end(); +} +``` + +ここに[Java でのコンテキスト抽出の例](/docs/languages/java/instrumentation/#context-propagation) の完全なものがあります。 + +メッセージングシステムの場合、一度に複数のメッセージを受け取ることがあります。 +受信したメッセージは、作成したスパンの[_リンク_](/docs/languages/java/instrumentation/#create-spans-with-links)になります。 +詳しくは[メッセージング規約](/docs/specs/semconv/messaging/messaging-spans/)を参照してください（警告：メッセージング規約は[策定中](https://github.com/open-telemetry/oteps/pull/173) 🚧 です）。 + +### コンテキストを注入する {#injecting-context} + +外部呼び出しを行う場合、通常はコンテキストを下流のサービスに伝搬させたくなります。 +この場合、外部呼び出しをトレースする新しいスパンを作成し、`Propagator` API を使ってメッセージにコンテキストを注入します。 +非同期処理用のメッセージを作成する場合など、コンテキストを注入したいケースは他にもあるかもしれません。 + +```java +Span span = tracer.spanBuilder("send") + .setSpanKind(SpanKind.CLIENT) + .startSpan(); + +// スパンをアクティブにすることで、ネスト化されたテレメトリを相関させる +// ネットワークコールでも、スパン、ログ、イベントのネスト化されたレイヤーがあるかもしれない +try (Scope unused = span.makeCurrent()) { + // コンテキストを注入 + propagator.inject(Context.current(), transportLayer, setter); + send(); +} catch (Exception e) { + span.recordException(e); + span.setStatus(StatusCode.ERROR); + throw e; +} finally { + span.end(); +} +``` + +[Javaにおけるコンテキスト注入の例](/docs/languages/java/instrumentation/#context-propagation)の全体はこちらを参照してください。 + +下記のように例外もあるかもしれません。 + +- 下流のサービスはメタデータをサポートしていないか、未知のフィールドを禁止している +- 下流のサービスが相関プロトコルを定義していない。将来のサービスのバージョンで、互換性のあるコンテキスト伝播がサポートされる可能性はありますか。ないなら入れましょう！ +- 下流のサービスは、カスタム相関プロトコルをサポートしている + - カスタムプロパゲーターでベストエフォートで対応している。互換性があればOpenTelemetryトレースコンテキストを使いましょう。 + - あるいはスパンにカスタム相関IDを生成して埋め込みましょう。 + +### プロセス内 {#in-process} + +- **スパンをアクティブにする**（別名カレント）。スパンをログやネストされた自動計装と関連付けられます。 +- ライブラリーにコンテキストの概念がある場合、アクティブスパンに加えて、**オプションで**明示的なトレースコンテキストの伝搬をサポートしましょう。 + - ライブラリが作成したスパン（トレースコンテキスト）を明示的にコンテキストに置き、そのアクセス方法をドキュメント化しましょう。 + - ユーザーが自分のコンテキストにトレースコンテキストを渡せるようにしましょう。 +- ライブラリ内で、トレースコンテキストを明示的に伝播させましょう。コールバック中にアクティブなスパンが変更される可能性があります！ + - パブリックAPIの上のユーザーからアクティブなコンテキストをできるだけ早く取得し、それをスパンの親コンテキストとして使用します。 + - コンテキストを受け渡し、明示的に伝播されたインスタンスに属性、例外、イベントを埋め込みます。 + - これは、スレッドを明示的に開始したり、バックグラウンド処理を行ったり、その他、使用する言語の非同期コンテキストフローの制限によって壊れる可能性がある場合に不可欠です。 + +## その他 {#misc} + +### 計装レジストリ {#instrumentation-registry} + +[OpenTelemetryレジストリ](/ecosystem/registry/)にあなたの計装ライブラリを追加してください。 + +### パフォーマンス {#performance} + +OpenTelemetryのAPIは、アプリケーションにSDKがない場合、no-opで、非常にパフォーマンスが良いです。 +OpenTelemetry SDK が設定されると、[バインドされたリソースを消費します](/docs/specs/otel/performance/)。 + +実際のアプリケーション、特に大規模なものでは、ヘッドベースのサンプリングが頻繁に設定されます。 +サンプリングアウトされたスパンは安価であり、属性の入力中に余分な割り当てや高価な計算を避けるために、スパンが記録されているかどうかをチェックできます。 + +```java +// サンプリングに重要な属性がある場合は、作成時に提供する必要がある +Span span = tracer.spanBuilder(String.format("SELECT %s.%s", dbName, collectionName)) + .setSpanKind(SpanKind.CLIENT) + .setAttribute("db.name", dbName) + ... + .startSpan(); + +// スパンが記録される場合は、他の属性、特に計算コストのかかる属性を追加する必要がある +if (span.isRecording()) { + span.setAttribute("db.statement", sanitize(query.statement())) +} +``` + +### エラーハンドリング {#error-handling} + +OpenTelemetry APIは、[実行時に寛容です](/docs/specs/otel/error-handling/#basic-error-handling-principles)。 +無効な引数では失敗せず、決して例外をスローせずに飲み込みます。 +このようにして、計装の問題がアプリケーションロジックに影響を与えないようにします。 +OpenTelemetry が実行時に隠す問題に気づくために、計装をテストしてください。 + +### テスト {#testing} + +OpenTelemetry にはさまざまな自動計装があるので、あなたの計装が他のテレメトリー（受信リクエスト、送信リクエスト、ログなど）とどのように相互作用するかを試してみるのは便利です。 +計装を試すときは、一般的なフレームワークとライブラリを使い、すべてのトレースを有効にした典型的なアプリケーションを使ってください。 +あなたのライブラリと似たライブラリがどのように表示されるかをチェックしてください。 + +ユニットテストでは、通常、`SpanProcessor`と`SpanExporter`をモックまたはフェイクできます。 + +```java +@Test +public void checkInstrumentation() { + SpanExporter exporter = new TestExporter(); + + Tracer tracer = OpenTelemetrySdk.builder() + .setTracerProvider(SdkTracerProvider.builder() + .addSpanProcessor(SimpleSpanProcessor.create(exporter)).build()).build() + .getTracer("test"); + // テストを実行... + + validateSpans(exporter.exportedSpans); +} + +class TestExporter implements SpanExporter { + public final List exportedSpans = Collections.synchronizedList(new ArrayList<>()); + + @Override + public CompletableResultCode export(Collection spans) { + exportedSpans.addAll(spans); + return CompletableResultCode.ofSuccess(); + } + ... +} +``` + +[instrumentation libraries]: /docs/specs/otel/overview/#instrumentation-libraries +[span events]: /docs/specs/otel/trace/api/#add-events diff --git a/content/ja/docs/concepts/instrumentation/zero-code.md b/content/ja/docs/concepts/instrumentation/zero-code.md new file mode 100644 index 000000000000..c04e70d7ba49 --- /dev/null +++ b/content/ja/docs/concepts/instrumentation/zero-code.md @@ -0,0 +1,39 @@ +--- +title: ゼロコード +description: >- + コードを書かずにアプリケーションにオブザーバビリティを追加する方法を学ぶ +weight: 10 +default_lang_commit: d8c5612 +--- + +[運用担当者](/docs/getting-started/ops/)として、ソースを編集することなく、1つ以上のアプリケーションにオブザーバビリティを追加したいと思うかもしれません。 +OpenTelemetry を使えば、[コードベースの計装](/docs/concepts/instrumentation/code-based) のための OpenTelemetry API & SDK を使わなくても、サービスのオブザーバビリティを素早く得られます。 + +ゼロコード計装は、OpenTelemetry APIとSDKの機能を使って、通常、エージェントあるいはそれに準ずる機能をアプリケーションに追加します。 +具体的なメカニズムは言語によって異なり、バイトコード操作、モンキーパッチ、あるいはeBPFから、アプリケーションにOpenTelemetry APIとSDKへの呼び出しを注入します。 + +通常、ゼロコード計装は、使用しているライブラリの計装を追加します。 +つまり、リクエストとレスポンス、データベース呼び出し、メッセージキュー呼び出しなどが計装の対象となります。 +しかし、アプリケーションのコードは通常、計装されません。 +コードを計装するには、[コードベース計装](/docs/concepts/instrumentation/code-based)を使う必要があります。 + +さらに、ゼロコード計装では、読み込まれた[計装ライブラリ](/docs/concepts/instrumentation/libraries)や[エクスポーター](/docs/concepts/components/#exporters)を設定を行うことができます。 + +環境変数や、システムプロパティや初期化メソッドに渡される引数のような他の言語固有のメカニズムを通して、ゼロコード計装を設定できます。 +開始するには、選択したオブザーバビリティバックエンドでサービスを識別できるように設定されたサービス名だけが必要です。 + +その他、以下のような設定オプションがあります。 + +- データソース固有の設定 +- エクスポーターの設定 +- プロパゲーターの設定 +- リソースの設定 + +ゼロコード計装は以下の言語に対応しています。 + +- [.NET](/docs/zero-code/net/) +- [Go](/docs/zero-code/go) +- [Java](/docs/zero-code/java/) +- [JavaScript](/docs/zero-code/js/) +- [PHP](/docs/zero-code/php/) +- [Python](/docs/zero-code/python/) From bf49f3af6181982e0915720747c3e214e1f89d28 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Tue, 23 Jul 2024 20:19:13 +0200 Subject: [PATCH 03/13] Remove bot token from component-owners.yml (#4869) --- .github/workflows/component-owners.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/component-owners.yml b/.github/workflows/component-owners.yml index 5429dc4ae505..7615888440d9 100644 --- a/.github/workflows/component-owners.yml +++ b/.github/workflows/component-owners.yml @@ -6,8 +6,10 @@ jobs: run_self: runs-on: ubuntu-latest name: Assign component owners + permissions: + contents: read + pull-requests: write steps: - uses: dyladan/component-owners@v0.1.0 with: config-file: .github/component-owners.yml - repo-token: ${{ secrets.OPENTELEMETRYBOT_GITHUB_TOKEN }} From 114d136a9afead18590aec4eadbe003104b84e06 Mon Sep 17 00:00:00 2001 From: Jamie Danielson Date: Wed, 24 Jul 2024 05:55:18 -0400 Subject: [PATCH 04/13] [operator/nodejs] document disabling node auto-instrumentations (#4824) --- .../en/docs/kubernetes/operator/automatic.md | 26 +++++++++++ content/en/docs/zero-code/js/configuration.md | 43 ++++++++++++++++--- 2 files changed, 63 insertions(+), 6 deletions(-) diff --git a/content/en/docs/kubernetes/operator/automatic.md b/content/en/docs/kubernetes/operator/automatic.md index 3fe3c12a41f6..00bd1227fa36 100644 --- a/content/en/docs/kubernetes/operator/automatic.md +++ b/content/en/docs/kubernetes/operator/automatic.md @@ -300,6 +300,32 @@ spec: value: http,nestjs-core # comma-separated list of the instrumentation package names without the `@opentelemetry/instrumentation-` prefix. ``` +To keep all default libraries and disable only specific instrumentation +libraries you can use the `OTEL_NODE_DISABLED_INSTRUMENTATIONS` environment +variable. For details, see +[Excluding instrumentation libraries](/docs/zero-code/js/configuration/#excluding-instrumentation-libraries). + +```yaml +apiVersion: opentelemetry.io/v1alpha1 +kind: Instrumentation +# ... other fields skipped from this example +spec: + # ... other fields skipped from this example + nodejs: + env: + - name: OTEL_NODE_DISABLED_INSTRUMENTATIONS + value: fs,grpc # comma-separated list of the instrumentation package names without the `@opentelemetry/instrumentation-` prefix. +``` + +{{% alert title="Note" color="info" %}} + +If both environment variables are set, `OTEL_NODE_ENABLED_INSTRUMENTATIONS` is +applied first, and then `OTEL_NODE_DISABLED_INSTRUMENTATIONS` is applied to that +list. Therefore, if the same instrumentation is included in both lists, that +instrumentation will be disabled. + +{{% /alert %}} + #### Learn more {#js-learn-more} For more details, see diff --git a/content/en/docs/zero-code/js/configuration.md b/content/en/docs/zero-code/js/configuration.md index 0511991b6373..3bf7fc47cf99 100644 --- a/content/en/docs/zero-code/js/configuration.md +++ b/content/en/docs/zero-code/js/configuration.md @@ -45,17 +45,22 @@ For example, to only enable the `env` and `host` detectors, you can set: OTEL_NODE_RESOURCE_DETECTORS=env,host ``` -### Excluding instrumentation libraries +## Excluding instrumentation libraries By default, all [supported instrumentation libraries](https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/metapackages/auto-instrumentations-node/README.md#supported-instrumentations) -are enabled, but you can use the environment variable -`OTEL_NODE_ENABLED_INSTRUMENTATIONS` to enable only certain instrumentations by -providing a comma-separated list of the instrumentation library names without -the `@opentelemetry/instrumentation-` prefix. +are enabled, but you can use environment variables to enable or disable specific +instrumentations. + +### Enable specific instrumentations + +Use the environment variable `OTEL_NODE_ENABLED_INSTRUMENTATIONS` to enable only +certain instrumentations by providing a comma-separated list of the +instrumentation library names without the `@opentelemetry/instrumentation-` +prefix. For example, to enable only -[@opentelemetry/instrumentation-http](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-instrumentation-http) +[@opentelemetry/instrumentation-http](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-http) and [@opentelemetry/instrumentation-express](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-express) instrumentations: @@ -63,3 +68,29 @@ instrumentations: ```shell OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,express" ``` + +### Disable specific instrumentations + +Use the environment variable `OTEL_NODE_DISABLED_INSTRUMENTATIONS` to keep the +fully enabled list and only disable certain instrumentations by providing a +comma-separated list of the instrumentation library names without the +`@opentelemetry/instrumentation-` prefix. + +For example, to disable only +[@opentelemetry/instrumentation-fs](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/instrumentation-fs) +and +[@opentelemetry/instrumentation-grpc](https://github.com/open-telemetry/opentelemetry-js/tree/main/experimental/packages/opentelemetry-instrumentation-grpc) +instrumentations: + +```shell +OTEL_NODE_DISABLED_INSTRUMENTATIONS="fs,grpc" +``` + +{{% alert title="Note" color="info" %}} + +If both environment variables are set, `OTEL_NODE_ENABLED_INSTRUMENTATIONS` is +applied first, and then `OTEL_NODE_DISABLED_INSTRUMENTATIONS` is applied to that +list. Therefore, if the same instrumentation is included in both lists, that +instrumentation will be disabled. + +{{% /alert %}} From 5f14f6c2223187bbd2da0828afb257437f832cd8 Mon Sep 17 00:00:00 2001 From: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> Date: Wed, 24 Jul 2024 04:02:34 -0600 Subject: [PATCH 05/13] [collector] Remove references to the memory ballast extension (#4870) --- content/en/docs/collector/configuration.md | 2 -- content/en/docs/collector/troubleshooting.md | 3 --- content/en/docs/kubernetes/helm/collector.md | 3 --- data/registry/collector-extension-ballast.yml | 17 ----------------- 4 files changed, 25 deletions(-) delete mode 100644 data/registry/collector-extension-ballast.yml diff --git a/content/en/docs/collector/configuration.md b/content/en/docs/collector/configuration.md index 66f97743ea13..287241d478eb 100644 --- a/content/en/docs/collector/configuration.md +++ b/content/en/docs/collector/configuration.md @@ -545,8 +545,6 @@ extensions: health_check: pprof: zpages: - memory_ballast: - size_mib: 512 ``` > For detailed extension configuration, see the diff --git a/content/en/docs/collector/troubleshooting.md b/content/en/docs/collector/troubleshooting.md index 2483bddb0058..e21431c92f9b 100644 --- a/content/en/docs/collector/troubleshooting.md +++ b/content/en/docs/collector/troubleshooting.md @@ -207,9 +207,6 @@ extensions: - name: zpages stability: extension: Beta - - name: memory_ballast - stability: - extension: Deprecated - name: health_check stability: extension: Beta diff --git a/content/en/docs/kubernetes/helm/collector.md b/content/en/docs/kubernetes/helm/collector.md index 35ca41f770b1..6e83e8da3e90 100644 --- a/content/en/docs/kubernetes/helm/collector.md +++ b/content/en/docs/kubernetes/helm/collector.md @@ -42,8 +42,6 @@ exporters: debug: {} extensions: health_check: {} - memory_ballast: - size_in_percentage: 40 processors: batch: {} memory_limiter: @@ -78,7 +76,6 @@ receivers: service: extensions: - health_check - - memory_ballast pipelines: logs: exporters: diff --git a/data/registry/collector-extension-ballast.yml b/data/registry/collector-extension-ballast.yml deleted file mode 100644 index 7222358250f7..000000000000 --- a/data/registry/collector-extension-ballast.yml +++ /dev/null @@ -1,17 +0,0 @@ -# cSpell:ignore ballastextension -title: Memory Ballast -registryType: extension -language: collector -tags: - - ballast - - extension - - collector -license: Apache 2.0 -description: - Memory Ballast extension enables applications to configure memory ballast for - the process. -authors: - - name: OpenTelemetry Authors -urls: - repo: https://github.com/open-telemetry/opentelemetry-collector/tree/main/extension/ballastextension -createdAt: 2022-11-07 From 4029a5dceff48d96bb5a74054c0c78959d7ee02e Mon Sep 17 00:00:00 2001 From: OpenTelemetry Bot <107717825+opentelemetrybot@users.noreply.github.com> Date: Wed, 24 Jul 2024 12:12:30 +0200 Subject: [PATCH 06/13] Auto-update registry versions (e85a66c05b54f2c07e077737aa330f350b4a95d2) (#4873) Co-authored-by: Severin Neumann --- data/registry/instrumentation-dotnet-stackexchangeredis.yml | 2 +- data/registry/instrumentation-js-bullmq.yml | 2 +- data/registry/tools-ruby-sentry.yml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/data/registry/instrumentation-dotnet-stackexchangeredis.yml b/data/registry/instrumentation-dotnet-stackexchangeredis.yml index d00bb5def88b..30cf38d83b39 100644 --- a/data/registry/instrumentation-dotnet-stackexchangeredis.yml +++ b/data/registry/instrumentation-dotnet-stackexchangeredis.yml @@ -19,4 +19,4 @@ createdAt: 2022-10-28 package: registry: nuget name: OpenTelemetry.Instrumentation.StackExchangeRedis - version: 1.0.0-rc9.15 + version: 1.9.0-beta.1 diff --git a/data/registry/instrumentation-js-bullmq.yml b/data/registry/instrumentation-js-bullmq.yml index 6bd3e6fdc1d1..6d7768644cd5 100644 --- a/data/registry/instrumentation-js-bullmq.yml +++ b/data/registry/instrumentation-js-bullmq.yml @@ -17,4 +17,4 @@ createdAt: 2023-01-27 package: name: '@jenniferplusplus/opentelemetry-instrumentation-bullmq' registry: npm - version: 0.5.0 + version: 0.5.1 diff --git a/data/registry/tools-ruby-sentry.yml b/data/registry/tools-ruby-sentry.yml index ad7b9a67f60b..7a4f78005996 100644 --- a/data/registry/tools-ruby-sentry.yml +++ b/data/registry/tools-ruby-sentry.yml @@ -23,4 +23,4 @@ createdAt: 2023-01-31 package: registry: gems name: sentry-opentelemetry - version: 5.18.1 + version: 5.18.2 From 855b7ccb3ae3864e2decbfc163a7b07973d98e27 Mon Sep 17 00:00:00 2001 From: Sophie McKay <42815245+SophieMcK@users.noreply.github.com> Date: Wed, 24 Jul 2024 12:35:30 +0100 Subject: [PATCH 07/13] Update integrations.yaml with APImetrics (#4865) --- data/ecosystem/integrations.yaml | 6 ++++++ static/refcache.json | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/data/ecosystem/integrations.yaml b/data/ecosystem/integrations.yaml index d231f8456fd0..c17e852fa713 100644 --- a/data/ecosystem/integrations.yaml +++ b/data/ecosystem/integrations.yaml @@ -310,3 +310,9 @@ components: [C++, Java, Go, Python] oss: true cncf: incubating +- name: APImetrics + url: https://apicontext.com/ + docsUrl: https://docs.apimetrics.io/docs/export-with-opentelemetry + components: [Python] + oss: false + cncf: false diff --git a/static/refcache.json b/static/refcache.json index aa6044a2accf..8c7fd6012a92 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -75,6 +75,10 @@ "StatusCode": 200, "LastSeen": "2024-01-18T08:05:43.542109-05:00" }, + "https://apicontext.com/": { + "StatusCode": 200, + "LastSeen": "2024-07-24T10:16:33.431203777Z" + }, "https://apisix.apache.org/blog/2022/02/28/apisix-integration-opentelemetry-plugin/": { "StatusCode": 206, "LastSeen": "2024-01-18T08:05:33.06745-05:00" @@ -871,6 +875,10 @@ "StatusCode": 206, "LastSeen": "2024-03-19T11:21:52.991213698Z" }, + "https://docs.apimetrics.io/docs/export-with-opentelemetry": { + "StatusCode": 200, + "LastSeen": "2024-07-24T10:16:35.028948386Z" + }, "https://docs.appdynamics.com/latest/en/application-monitoring/appdynamics-for-opentelemetry": { "StatusCode": 200, "LastSeen": "2024-01-18T08:51:22.195056-05:00" From d76b9bdbc71e3357e3b8607a18914aca6d24fe84 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Wed, 24 Jul 2024 16:31:52 +0200 Subject: [PATCH 08/13] zero-code/python: correct the OTEL_PYTHON_DISABLED_INSTRUMENTATIONS description (#4866) --- .../en/docs/zero-code/python/configuration.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/content/en/docs/zero-code/python/configuration.md b/content/en/docs/zero-code/python/configuration.md index f0c33f567498..bf8ea7169743 100644 --- a/content/en/docs/zero-code/python/configuration.md +++ b/content/en/docs/zero-code/python/configuration.md @@ -165,12 +165,16 @@ in too much or unwanted data. You can omit specific packages from instrumentation by using the `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS` environment variable. The environment -variable can be set to a comma-separated list of package names to exclude from -instrumentation. +variable can be set to a comma-separated list of instrumentations entry point +names to exclude from instrumentation. Most of the time the entry point name is +the same as the package name and it is set in the +`project.entry-points.opentelemetry_instrumentor` table in the package +`pyproject.toml` file. -For example, if your Python program uses the `redis` and `kafka-python` +For example, if your Python program uses the `redis`,`kafka-python` and `grpc` packages, by default the agent will use the -`opentelemetry-instrumentation-redis` and -`opentelemetry-instrumentation-kafka-python` packages to instrument them. To -disable this, you can set -`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=redis,kafka-python`. +`opentelemetry-instrumentation-redis`, +`opentelemetry-instrumentation-kafka-python` and +`opentelemetry-instrumentation-grpc` packages to instrument them. To disable +this, you can set +`OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=redis,kafka,grpc_client`. From 99dfcdebbc2ac469fa48488e76ae6f5bedf2f367 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Wed, 24 Jul 2024 16:45:00 +0200 Subject: [PATCH 09/13] Include Java example code excerpts (#4642) --- .gitmodules | 5 +- content-modules/opentelemetry-java-examples | 1 + content/en/docs/languages/java/exporters.md | 204 +++++++++++++----- .../en/docs/languages/java/getting-started.md | 11 +- .../java/spring-boot-starter/annotations.md | 33 ++- .../other-spring-autoconfig.md | 3 + .../out-of-the-box-instrumentation.md | 103 +++++++-- .../spring-boot-starter/sdk-configuration.md | 22 +- examples/java | 1 + scripts/check-markdown-wrapper.sh | 12 +- tools/content/java | 1 + tools/content/java-zero-code | 1 + 12 files changed, 313 insertions(+), 84 deletions(-) create mode 160000 content-modules/opentelemetry-java-examples create mode 120000 examples/java create mode 120000 tools/content/java create mode 120000 tools/content/java-zero-code diff --git a/.gitmodules b/.gitmodules index f7f168b39e8f..66a9ca1cac98 100644 --- a/.gitmodules +++ b/.gitmodules @@ -27,4 +27,7 @@ [submodule "content-modules/opentelemetry-go"] path = content-modules/opentelemetry-go url = https://github.com/open-telemetry/opentelemetry-go - go-pin = v1.27.0 + go-pin = v1.27.0 +[submodule "content-modules/opentelemetry-java-examples"] + path = content-modules/opentelemetry-java-examples + url = https://github.com/open-telemetry/opentelemetry-java-examples.git diff --git a/content-modules/opentelemetry-java-examples b/content-modules/opentelemetry-java-examples new file mode 160000 index 000000000000..4e11b9387241 --- /dev/null +++ b/content-modules/opentelemetry-java-examples @@ -0,0 +1 @@ +Subproject commit 4e11b93872415458ce260ce9799e259cd13b506a diff --git a/content/en/docs/languages/java/exporters.md b/content/en/docs/languages/java/exporters.md index 65d535ff4ecf..5bccb877e889 100644 --- a/content/en/docs/languages/java/exporters.md +++ b/content/en/docs/languages/java/exporters.md @@ -4,6 +4,9 @@ weight: 50 cSpell:ignore: okhttp --- + + + {{% docs/languages/exporters/intro java %}} ### Dependencies {#otlp-dependencies} @@ -18,7 +21,9 @@ suffice and be the most simple: ```kotlin dependencies { - implementation 'io.opentelemetry:opentelemetry-exporter-otlp:{{% param vers.otel %}}' + implementation("io.opentelemetry:opentelemetry-exporter-otlp:{{% param vers.otel %}}") + implementation("io.opentelemetry:opentelemetry-sdk:{{% param vers.otel %}}") + implementation("io.opentelemetry.semconv:opentelemetry-semconv:{{% param vers.semconv %}}-alpha") } ``` @@ -31,6 +36,15 @@ dependencies { io.opentelemetry opentelemetry-exporter-otlp + + io.opentelemetry + opentelemetry-sdk + + + io.opentelemetry.semconv + opentelemetry-semconv + {{% param vers.semconv %}}-alpha + ``` @@ -94,31 +108,30 @@ Note, that in the case of exporting via OTLP you do not need to set In the case of [manual configuration] you can update the [example app](/docs/languages/java/instrumentation#example-app) like the following: -```java { hl_lines=["12-14",21,"39-53"] } + + +```java package otel; -import org.springframework.boot.SpringApplication; -import org.springframework.boot.Banner; -import org.springframework.boot.autoconfigure.SpringBootApplication; -import org.springframework.context.annotation.Bean; - import io.opentelemetry.api.OpenTelemetry; -import io.opentelemetry.api.common.Attributes; import io.opentelemetry.api.trace.propagation.W3CTraceContextPropagator; import io.opentelemetry.context.propagation.ContextPropagators; +import io.opentelemetry.exporter.otlp.logs.OtlpGrpcLogRecordExporter; import io.opentelemetry.exporter.otlp.metrics.OtlpGrpcMetricExporter; import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter; -import io.opentelemetry.exporter.otlp.logs.OtlpGrpcLogRecordExporter; import io.opentelemetry.sdk.OpenTelemetrySdk; +import io.opentelemetry.sdk.logs.SdkLoggerProvider; +import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor; import io.opentelemetry.sdk.metrics.SdkMeterProvider; import io.opentelemetry.sdk.metrics.export.PeriodicMetricReader; import io.opentelemetry.sdk.resources.Resource; import io.opentelemetry.sdk.trace.SdkTracerProvider; import io.opentelemetry.sdk.trace.export.BatchSpanProcessor; -import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor; -import io.opentelemetry.sdk.logs.SdkLoggerProvider; -import io.opentelemetry.sdk.logs.export.LogRecordExporter; -import io.opentelemetry.semconv.resource.attributes.ResourceAttributes; +import io.opentelemetry.semconv.ServiceAttributes; +import org.springframework.boot.Banner; +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; +import org.springframework.context.annotation.Bean; @SpringBootApplication public class DiceApplication { @@ -130,35 +143,47 @@ public class DiceApplication { @Bean public OpenTelemetry openTelemetry() { - Resource resource = Resource.getDefault().toBuilder().put(SERVICE_NAME, "dice-server").put(SERVICE_VERSION, "0.1.0").build(); + Resource resource = + Resource.getDefault().toBuilder() + .put(ServiceAttributes.SERVICE_NAME, "dice-server") + .put(ServiceAttributes.SERVICE_VERSION, "0.1.0") + .build(); - SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()).build()) + SdkTracerProvider sdkTracerProvider = + SdkTracerProvider.builder() + .addSpanProcessor( + BatchSpanProcessor.builder(OtlpGrpcSpanExporter.builder().build()).build()) .setResource(resource) .build(); - SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder() - .registerMetricReader(PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build()).build()) + SdkMeterProvider sdkMeterProvider = + SdkMeterProvider.builder() + .registerMetricReader( + PeriodicMetricReader.builder(OtlpGrpcMetricExporter.builder().build()).build()) .setResource(resource) .build(); - SdkLoggerProvider sdkLoggerProvider = SdkLoggerProvider.builder() + SdkLoggerProvider sdkLoggerProvider = + SdkLoggerProvider.builder() .addLogRecordProcessor( - BatchLogRecordProcessor.builder(OtlpGrpcLogRecordExporter.builder().build()).build()) + BatchLogRecordProcessor.builder(OtlpGrpcLogRecordExporter.builder().build()) + .build()) .setResource(resource) .build(); - OpenTelemetry openTelemetry = OpenTelemetrySdk.builder() - .setTracerProvider(sdkTracerProvider) - .setMeterProvider(sdkMeterProvider) - .setLoggerProvider(sdkLoggerProvider) - .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance())) - .buildAndRegisterGlobal(); + OpenTelemetry openTelemetry = + OpenTelemetrySdk.builder() + .setTracerProvider(sdkTracerProvider) + .setMeterProvider(sdkMeterProvider) + .setLoggerProvider(sdkLoggerProvider) + .setPropagators(ContextPropagators.create(W3CTraceContextPropagator.getInstance())) + .buildAndRegisterGlobal(); return openTelemetry; } } ``` + ## Console @@ -217,15 +242,29 @@ dependencies { Update your OpenTelemetry configuration to use the exporter and to send data to your Prometheus backend: + + ```java +package otel; + import io.opentelemetry.exporter.prometheus.PrometheusHttpServer; +import io.opentelemetry.sdk.metrics.SdkMeterProvider; +import io.opentelemetry.sdk.resources.Resource; -int prometheusPort = 9464; -SdkMeterProvider sdkMeterProvider = SdkMeterProvider.builder() - .registerMetricReader(PrometheusHttpServer.builder().setPort(prometheusPort).build()) - .setResource(resource) - .build(); +public class PrometheusExporter { + public static SdkMeterProvider create(Resource resource) { + int prometheusPort = 9464; + SdkMeterProvider sdkMeterProvider = + SdkMeterProvider.builder() + .registerMetricReader(PrometheusHttpServer.builder().setPort(prometheusPort).build()) + .setResource(resource) + .build(); + + return sdkMeterProvider; + } +} ``` + With the above you can access your metrics at . Prometheus or an OpenTelemetry Collector with the Prometheus receiver can scrape @@ -268,53 +307,104 @@ dependencies { Update your OpenTelemetry configuration to use the exporter and to send data to your Zipkin backend: + + ```java +package otel; + import io.opentelemetry.exporter.zipkin.ZipkinSpanExporter; +import io.opentelemetry.sdk.resources.Resource; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.export.BatchSpanProcessor; -SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(BatchSpanProcessor.builder(ZipkinSpanExporter.builder().setEndpoint("http://localhost:9411/api/v2/spans").build()).build()) - .setResource(resource) - .build(); +public class ZipkinExporter { + public static SdkTracerProvider create(Resource resource) { + SdkTracerProvider sdkTracerProvider = + SdkTracerProvider.builder() + .addSpanProcessor( + BatchSpanProcessor.builder( + ZipkinSpanExporter.builder() + .setEndpoint("http://localhost:9411/api/v2/spans") + .build()) + .build()) + .setResource(resource) + .build(); + + return sdkTracerProvider; + } +} ``` + {{% docs/languages/exporters/outro java "https://javadoc.io/doc/io.opentelemetry/opentelemetry-sdk-trace/latest/io/opentelemetry/sdk/trace/export/SpanExporter.html" %}} {{< tabpane text=true >}} {{% tab Batch %}} + + ```java -import io.opentelemetry.sdk.trace.export.BatchSpanProcessor; -import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor; +package otel; -SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(BatchSpanProcessor.builder(...).build()) - .setResource(resource) - .build(); +import io.opentelemetry.sdk.logs.SdkLoggerProvider; +import io.opentelemetry.sdk.logs.export.BatchLogRecordProcessor; +import io.opentelemetry.sdk.logs.export.LogRecordExporter; +import io.opentelemetry.sdk.resources.Resource; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.export.BatchSpanProcessor; +import io.opentelemetry.sdk.trace.export.SpanExporter; + +public class BatchExporter { + public static void create( + Resource resource, SpanExporter spanExporter, LogRecordExporter logExporter) { + SdkTracerProvider sdkTracerProvider = + SdkTracerProvider.builder() + .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build()) + .setResource(resource) + .build(); -SdkLoggerProvider sdkLoggerProvider = SdkLoggerProvider.builder() - .addLogRecordProcessor( - BatchLogRecordProcessor.builder(...).build()) - .setResource(resource) - .build(); + SdkLoggerProvider sdkLoggerProvider = + SdkLoggerProvider.builder() + .addLogRecordProcessor(BatchLogRecordProcessor.builder(logExporter).build()) + .setResource(resource) + .build(); + } +} ``` {{% /tab %}} {{% tab Simple %}} + ```java -import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; -import io.opentelemetry.sdk.logs.export.SimpleLogRecordProcessor; +package otel; -SdkTracerProvider sdkTracerProvider = SdkTracerProvider.builder() - .addSpanProcessor(SimpleSpanProcessor.builder(...).build()) - .setResource(resource) - .build(); +import io.opentelemetry.sdk.logs.SdkLoggerProvider; +import io.opentelemetry.sdk.logs.export.LogRecordExporter; +import io.opentelemetry.sdk.logs.export.SimpleLogRecordProcessor; +import io.opentelemetry.sdk.resources.Resource; +import io.opentelemetry.sdk.trace.SdkTracerProvider; +import io.opentelemetry.sdk.trace.export.SimpleSpanProcessor; +import io.opentelemetry.sdk.trace.export.SpanExporter; + +public class SimpleExporter { + public static void create( + Resource resource, SpanExporter spanExporter, LogRecordExporter logExporter) { + SdkTracerProvider sdkTracerProvider = + SdkTracerProvider.builder() + .addSpanProcessor(SimpleSpanProcessor.builder(spanExporter).build()) + .setResource(resource) + .build(); -SdkLoggerProvider sdkLoggerProvider = SdkLoggerProvider.builder() - .addLogRecordProcessor( - SimpleLogRecordProcessor.builder(...).build()) - .setResource(resource) - .build(); + SdkLoggerProvider sdkLoggerProvider = + SdkLoggerProvider.builder() + .addLogRecordProcessor(SimpleLogRecordProcessor.create(logExporter)) + .setResource(resource) + .build(); + } +} ``` {{< /tab >}} {{< /tabpane>}} + + {{% /docs/languages/exporters/outro %}} diff --git a/content/en/docs/languages/java/getting-started.md b/content/en/docs/languages/java/getting-started.md index 7405286cb343..83555c56af26 100644 --- a/content/en/docs/languages/java/getting-started.md +++ b/content/en/docs/languages/java/getting-started.md @@ -4,6 +4,9 @@ description: Get telemetry for your app in less than 5 minutes! weight: 10 --- + + + This page will show you how to get started with OpenTelemetry in Java. You will learn how you can instrument a simple Java application automatically, @@ -58,11 +61,13 @@ dependencies { In that same folder, create a file called `DiceApplication.java` and add the following code to the file: + + ```java package otel; -import org.springframework.boot.SpringApplication; import org.springframework.boot.Banner; +import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication @@ -74,10 +79,13 @@ public class DiceApplication { } } ``` + Create another file called `RollController.java` and add the following code to the file: + + ```java package otel; @@ -109,6 +117,7 @@ public class RollController { } } ``` + Build and run the application with the following command, then open in your web browser to ensure it is working. diff --git a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md index 6e61a5f8d0f9..6cc42bdd2343 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/annotations.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/annotations.md @@ -4,6 +4,9 @@ weight: 50 cSpell:ignore: proxys --- + + + For most users, the out-of-the-box instrumentation is completely sufficient and nothing more has to be done. Sometimes, however, users wish to create [spans](/docs/concepts/signals/traces/#spans) for their own custom code without @@ -13,14 +16,38 @@ If you add the `WithSpan` annotation to a method, the method is wrapped in a span. The `SpanAttribute` annotation allows you to capture the method arguments as attributes. + + ```java +package otel; + +import io.opentelemetry.api.trace.Span; +import io.opentelemetry.api.trace.SpanKind; import io.opentelemetry.instrumentation.annotations.SpanAttribute; import io.opentelemetry.instrumentation.annotations.WithSpan; +import org.springframework.stereotype.Component; - @WithSpan - public void tracedMethod(@SpanAttribute parameter) { - } +/** Test WithSpan */ +@Component +public class TracedClass { + + @WithSpan + public void tracedMethod() {} + + @WithSpan(value = "span name") + public void tracedMethodWithName() { + Span currentSpan = Span.current(); + currentSpan.addEvent("ADD EVENT TO tracedMethodWithName SPAN"); + currentSpan.setAttribute("isTestAttribute", true); + } + + @WithSpan(kind = SpanKind.CLIENT) + public void tracedClientSpan() {} + + public void tracedMethodWithAttribute(@SpanAttribute("attributeName") String parameter) {} +} ``` + {{% alert title="Note" color="info" %}} The OpenTelemetry annotations use Spring AOP based on proxys. diff --git a/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md b/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md index 012e9c060fb6..72bb28f9c7ea 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/other-spring-autoconfig.md @@ -4,6 +4,9 @@ cSpell:ignore: autoconfigurations weight: 70 --- + + + Instead of using the OpenTelemetry Spring starter, you can use the OpenTelemetry Zipkin starter. diff --git a/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md b/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md index e0aa2330fe81..afeef32904fe 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/out-of-the-box-instrumentation.md @@ -4,6 +4,9 @@ weight: 40 cSpell:ignore: autoconfigurations autoconfigures logback webflux webmvc --- + + + Out of the box instrumentation is available for several frameworks: | Feature | Property | Default Value | @@ -99,33 +102,84 @@ supported for spring web versions 3.1+. To learn more about the OpenTelemetry The following ways of creating a `RestTemplate` are supported: + + ```java -@Bean -public RestTemplate restTemplate() { +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestTemplate; + +@Configuration +public class RestTemplateConfig { + + @Bean + public RestTemplate restTemplate() { return new RestTemplate(); + } } ``` + ```java -public MyService(RestTemplateBuilder restTemplateBuilder) { - this.restTemplate = restTemplateBuilder.build(); +package otel; + +import org.springframework.boot.web.client.RestTemplateBuilder; +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.client.RestTemplate; + +@RestController +public class RestTemplateController { + + private final RestTemplate restTemplate; + + public RestTemplateController(RestTemplateBuilder restTemplateBuilder) { + restTemplate = restTemplateBuilder.rootUri("http://localhost:8080").build(); + } } ``` + The following ways of creating a `RestClient` are supported: + + ```java -@Bean -public RestClient restClient() { +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestClient; + +@Configuration +public class RestClientConfig { + + @Bean + public RestClient restClient() { return RestClient.create(); + } } ``` + ```java -public MyService(RestClient.Builder restClientBuilder) { - this.restClient = restClientBuilder.build(); +package otel; + +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.client.RestClient; + +@RestController +public class RestClientController { + + private final RestClient restClient; + + public RestClientController(RestClient.Builder restClientBuilder) { + restClient = restClientBuilder.baseUrl("http://localhost:8080").build(); + } } ``` + As it's possible with the Java agent, you can configure the capture of the following entities: @@ -165,18 +219,43 @@ details, see The following ways of creating a `WebClient` are supported: + + ```java -@Bean -public WebClient webClient() { +package otel; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.reactive.function.client.WebClient; + +@Configuration +public class WebClientConfig { + + @Bean + public WebClient webClient() { return WebClient.create(); + } } ``` + ```java -public MyService(WebClient.Builder webClientBuilder) { - this.webClient = webClientBuilder.build(); +package otel; + +import org.springframework.web.bind.annotation.RestController; +import org.springframework.web.reactive.function.client.WebClient; + +@RestController +public class WebClientController { + + private final WebClient webClient; + + public WebClientController(WebClient.Builder webClientBuilder) { + webClient = webClientBuilder.baseUrl("http://localhost:8080").build(); + } } ``` + ## Kafka Instrumentation diff --git a/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md b/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md index c226c55dd0c3..2f839838db6b 100644 --- a/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md +++ b/content/en/docs/zero-code/java/spring-boot-starter/sdk-configuration.md @@ -4,6 +4,9 @@ weight: 30 cSpell:ignore: customizer distro --- + + + This spring starter supports [configuration metadata](https://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html), which means that you can see and autocomplete all available properties in your @@ -119,16 +122,20 @@ dependencies { {{% /tab %}} {{< /tabpane>}} + + ```java +package otel; + import io.opentelemetry.api.trace.SpanKind; import io.opentelemetry.contrib.sampler.RuleBasedRoutingSampler; import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; -import io.opentelemetry.semconv.SemanticAttributes; +import io.opentelemetry.semconv.UrlAttributes; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration -public class OpenTelemetryConfig { +public class FilterPaths { @Bean public AutoConfigurationCustomizerProvider otelCustomizer() { @@ -136,18 +143,23 @@ public class OpenTelemetryConfig { p.addSamplerCustomizer( (fallback, config) -> RuleBasedRoutingSampler.builder(SpanKind.SERVER, fallback) - .drop(SemanticAttributes.URL_PATH, "^/actuator") + .drop(UrlAttributes.URL_PATH, "^/actuator") .build()); } } ``` + ### Configure the exporter programmatically You can also configure OTLP exporters programmatically. This configuration replaces the default OTLP exporter and adds a custom header to the requests. + + ```java +package otel; + import io.opentelemetry.exporter.otlp.http.trace.OtlpHttpSpanExporter; import io.opentelemetry.sdk.autoconfigure.spi.AutoConfigurationCustomizerProvider; import java.util.Collections; @@ -156,8 +168,7 @@ import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration -public class OpenTelemetryConfig { - +public class CustomAuth { @Bean public AutoConfigurationCustomizerProvider otelCustomizer() { return p -> @@ -181,6 +192,7 @@ public class OpenTelemetryConfig { } } ``` + ## Resource Providers diff --git a/examples/java b/examples/java new file mode 120000 index 000000000000..17320458ee39 --- /dev/null +++ b/examples/java @@ -0,0 +1 @@ +../content-modules/opentelemetry-java-examples/doc-snippets \ No newline at end of file diff --git a/scripts/check-markdown-wrapper.sh b/scripts/check-markdown-wrapper.sh index 045eeed03949..b960dcabc335 100755 --- a/scripts/check-markdown-wrapper.sh +++ b/scripts/check-markdown-wrapper.sh @@ -3,12 +3,14 @@ # @chalin can't get Gulp 5 to ignore symlinks, so this wrapper creates # bogus symlink targets to make the check:markdown Gulp task happy. -symlink_target="content-modules/opentelemetry-go/example" +symlink_targets="content-modules/opentelemetry-go/example content-modules/opentelemetry-java-examples/doc-snippets" -if [[ ! -e $symlink_target ]]; then - echo "WARNING: required symlink target does not exist, creating it: $symlink_target" - (set -x; mkdir -p $symlink_target) -fi +for symlink_target in $symlink_targets; do + if [[ ! -e $symlink_target ]]; then + echo "WARNING: required symlink target does not exist, creating it: $symlink_target" + (set -x; mkdir -p "$symlink_target") + fi +done set -x exec npm run _check:markdown "$@" diff --git a/tools/content/java b/tools/content/java new file mode 120000 index 000000000000..f52d927cd39b --- /dev/null +++ b/tools/content/java @@ -0,0 +1 @@ +../../content/en/docs/languages/java \ No newline at end of file diff --git a/tools/content/java-zero-code b/tools/content/java-zero-code new file mode 120000 index 000000000000..da11c8f4ef70 --- /dev/null +++ b/tools/content/java-zero-code @@ -0,0 +1 @@ +../../content/en/docs/zero-code/java \ No newline at end of file From 82c72490dbf1765211ec69acab589723c6665433 Mon Sep 17 00:00:00 2001 From: Dariel Li Date: Thu, 25 Jul 2024 06:24:04 +0800 Subject: [PATCH 10/13] [zh] add contributing/style-guide.md (#4685) --- content/zh/docs/contributing/style-guide.md | 85 +++++++++++++++++++++ 1 file changed, 85 insertions(+) create mode 100644 content/zh/docs/contributing/style-guide.md diff --git a/content/zh/docs/contributing/style-guide.md b/content/zh/docs/contributing/style-guide.md new file mode 100644 index 000000000000..24ad8a816096 --- /dev/null +++ b/content/zh/docs/contributing/style-guide.md @@ -0,0 +1,85 @@ +--- +title: 文档风格指南 +description: 编写 OpenTelemetry 文档时的术语和风格指南。 +linkTitle: 风格指南 +weight: 20 +cSpell:ignore: open-telemetry postgre style-guide textlintrc +default_lang_commit: d78e63a +--- + +OpenTelemetry 还没有官方的风格指南，当前版本的 OpenTelemetry 文档风格受到以下风格指南的启发： + +- [Google 开发者文档风格指南](https://developers.google.com/style) +- [Kubernetes 风格指南](https://kubernetes.io/docs/contribute/style/style-guide/) + +以下部分包含针对 OpenTelemetry 项目的特定指导。 + +{{% alert title="说明" color="primary" %}} + +我们的风格指南中许多要求都可以通过命令来自动化执行： +在发起[拉取请求](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)(PR) 之前，你可以在本地机器上运行 `npm run fix:all` 命令并提交更改。 + +如果你遇到错误或 [PR 检查失败](/docs/contributing/pr-checks)，请阅读以下关于我们的风格指南的内容以及了解你可以采取哪些措施来解决某些常见问题。 + +{{% /alert %}} + +## OpenTelemetry.io 单词列表 + +请在整个网站上统一使用以下 OpenTelemetry 特定术语和词语列表。 + + + +| Term | Usage | +| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| OpenTelemetry | OpenTelemetry 应始终大写。请勿使用 Open-Telemetry。 | +| OTel | OTel 是 OpenTelemetry 的公认缩写形式。请勿使用 OTEL。 | +| Collector | 当引用 OpenTelemetry Collector 时，请始终将 Collector 大写。在句子开头请使用 `The Collector` 或 `The Opentelemetry Collector`， 在句中或句尾则使用 `the Collector` 或 `the OpenTelemetry Collector`。如果您要将 Collector 用作形容词（例如， `Collector 配置` ），请只使用 `Collector` 。 | +| OTEP | OpenTelemetry 增强提案（OpenTelemetry Enhancement Proposal）。复数形式请写作 `OTEPs` 。请不要写成 `OTep` 或 `otep`。 | +| OpAMP | 开放代理管理协议（Open Agent Management Protocol）。请勿在描述或说明中写成 `OPAMP` 或 `opamp`。 | +| | | + +确保正确书写专有名词（例如其他 CNCF 项目或第三方工具）并使用原始大写字母。例如，书写 `PostgreSQL` 而不是 `postgre`。有关完整列表，请查看 [`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) 文件。 + +另请参阅 [词汇表](/docs/concepts/glossary/) 以获取 OpenTelemetry术语及其定义的列表。 + +运行 `npm run check:text` 命令以验证所有术语和单词是否书写正确。 + +运行 `npm run check:text -- --fix` 命令以修复书写不正确的术语和单词。 + +## Markdown 标准 + +为了增强 Markdown 文件的标准性和一致性，所有文件都应遵循 [markdownlint](https://github.com/DavidAnson/markdownlint) 确定的相关规则。有关完整列表，请查看 [`.markdownlint.json`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.json) 文件。 + +运行 `npm run check:markdown` 命令以验证所有文件是否遵循标准。 + +运行 `npm run fix:markdown` 命令以修复与 Markdown 相关的格式问题。 + +## 拼写检查 + +使用 [CSpell](https://github.com/streetsidesoftware/cspell) 确保所有文本拼写正确。有关 OpenTelemetry 网站特定单词的列表，请参阅 [`.cspell.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml) 文件。 + +运行 `npm run check:spelling` 命令以验证所有单词拼写是否正确。如果 `cspell` 指示 `Unknown word` 错误，请验证您是否正确编写了该单词。如果正确，请将此单词添加到文件顶部的 `cSpell:ignore` 部分。如果不存在这样的部分，您可以将其添加到 Markdown 文件的元数据中： + +```markdown +--- +title: PageTitle +cSpell:ignore: +--- +``` + +对于任何其他文件，请在适合文件上下文的注释行中添加 `cSpell:ignore `。对于 [registry](/ecosystem/registry/) 条目 YAML 文件，它可能看起来像这样： + +```yaml +# cSpell:ignore +title: registryEntryTitle +``` + +网站工具通过移除重复单词、删除全局单词列表中的单词以及对单词进行排序来规范特定于页面的词典（即 `cSpell:ignore` 单词列表）。要规范特定于页面的词典，请运行 `npm run fix:dict`。 + +## 文件格式 + +为了执行关于文件结构的特定标准，所有文件都应使用 [prettier](https://prettier.io) 进行格式化。在提交 PR 之前运行 `npm run fix:format`，或者在提交 PR 之后运行它并推送额外的提交。 + +## 文件名 + +所有文件名都应采用[短横线命名](https://en.wikipedia.org/wiki/Letter_case#Kebab_case)。运行 `npm run fix:filenames` 以自动重命名文件。 From 78f1d31f5612ae75df7ffb06702babaf0cbddb7a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 24 Jul 2024 20:15:18 -0400 Subject: [PATCH 11/13] Fix spelling issues, update page-local dictionaries (#4877) --- .cspell.yml | 1 + content-modules/opentelemetry-java-examples | 2 +- content/en/blog/2024/cve-2024-36129.md | 2 +- content/en/blog/2024/hardening-the-collector-one.md | 2 +- content/en/docs/languages/java/performance.md | 1 + content/en/docs/zero-code/java/agent/configuration.md | 1 + content/en/docs/zero-code/python/configuration.md | 2 +- 7 files changed, 7 insertions(+), 4 deletions(-) diff --git a/.cspell.yml b/.cspell.yml index 1093a17f4591..5ea76c9a3843 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -104,6 +104,7 @@ words: - opentelemetry - opentracing - openzipkin + - OSTIF - otel - otel-comms - otel-endusers diff --git a/content-modules/opentelemetry-java-examples b/content-modules/opentelemetry-java-examples index 4e11b9387241..4cbbe362fabc 160000 --- a/content-modules/opentelemetry-java-examples +++ b/content-modules/opentelemetry-java-examples @@ -1 +1 @@ -Subproject commit 4e11b93872415458ce260ce9799e259cd13b506a +Subproject commit 4cbbe362fabc68c017d6431859fef98d9e118862 diff --git a/content/en/blog/2024/cve-2024-36129.md b/content/en/blog/2024/cve-2024-36129.md index 363c7e0db906..4f75b1d45377 100644 --- a/content/en/blog/2024/cve-2024-36129.md +++ b/content/en/blog/2024/cve-2024-36129.md @@ -8,7 +8,7 @@ author: '[Juraci Paixão Kröhling](https://github.com/jpkrohling) (OpenTelemetry, Grafana Labs), [Pablo Baeyens](https://github.com/mx-psi) (OpenTelemetry, Datadog)' -cSpell:ignore: Baeyens configgrpc confighttp Miroslav OSTIF Stampar zstd +cSpell:ignore: Baeyens configgrpc confighttp Miroslav Stampar zstd --- On our path toward graduation, the OpenTelemetry project is currently undergoing diff --git a/content/en/blog/2024/hardening-the-collector-one.md b/content/en/blog/2024/hardening-the-collector-one.md index 12d92c0976d3..57ef5a0b6846 100644 --- a/content/en/blog/2024/hardening-the-collector-one.md +++ b/content/en/blog/2024/hardening-the-collector-one.md @@ -4,7 +4,7 @@ linkTitle: A new default bind address for the Collector date: 2024-07-02 author: '[Pablo Baeyens](https://github.com/mx-psi) (OpenTelemetry, Datadog)' # prettier-ignore -cSpell:ignore: awsfirehose awsproxy awsxray Baeyens jaegerremotesampling loki OSTIF remotetap sapm signalfx skywalking splunk +cSpell:ignore: awsfirehose awsproxy awsxray Baeyens jaegerremotesampling loki remotetap sapm signalfx skywalking splunk issue: 4760 sig: Collector SIG --- diff --git a/content/en/docs/languages/java/performance.md b/content/en/docs/languages/java/performance.md index d47dae31e231..cf290a190209 100644 --- a/content/en/docs/languages/java/performance.md +++ b/content/en/docs/languages/java/performance.md @@ -2,6 +2,7 @@ title: Performance description: Performance reference for the OpenTelemetry Java agent weight: 75 +cSpell:ignore: Dotel --- The OpenTelemetry Java agent instruments your application by running inside the diff --git a/content/en/docs/zero-code/java/agent/configuration.md b/content/en/docs/zero-code/java/agent/configuration.md index 3bfe107acd08..1df2d9dbec15 100644 --- a/content/en/docs/zero-code/java/agent/configuration.md +++ b/content/en/docs/zero-code/java/agent/configuration.md @@ -2,6 +2,7 @@ title: Configuration weight: 10 aliases: [agent-config] +cSpell:ignore: classloaders customizer logback --- ## Agent Configuration diff --git a/content/en/docs/zero-code/python/configuration.md b/content/en/docs/zero-code/python/configuration.md index bf8ea7169743..12125c653c82 100644 --- a/content/en/docs/zero-code/python/configuration.md +++ b/content/en/docs/zero-code/python/configuration.md @@ -6,7 +6,7 @@ aliases: - /docs/languages/python/automatic/configuration - /docs/languages/python/automatic/agent-config # prettier-ignore -cSpell:ignore: distro healthcheck mkdir myapp Starlette uninstrumented urllib virtualenv +cSpell:ignore: distro healthcheck instrumentor mkdir myapp pyproject Starlette uninstrumented urllib virtualenv --- The agent is highly configurable, either by: From a470b92bf6f12bd844b41443ff4b6c311de78acc Mon Sep 17 00:00:00 2001 From: hyang023 Date: Thu, 25 Jul 2024 02:57:08 -0700 Subject: [PATCH 12/13] Documentation: Context propagation (#4878) --- content/en/docs/concepts/context-propagation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/concepts/context-propagation.md b/content/en/docs/concepts/context-propagation.md index 31537ffddc70..2c4b042d84b7 100644 --- a/content/en/docs/concepts/context-propagation.md +++ b/content/en/docs/concepts/context-propagation.md @@ -33,7 +33,7 @@ information to be propagated from one service to another. Propagation is usually handled by instrumentation libraries and is transparent to the user. In the event that you need to manually propagate context, you can -use Propagation APIs. +use the [Propagators API](/docs/specs/otel/context/api-propagators/). OpenTelemetry maintains several official propagators. The default propagator is using the headers specified by the From 2a06b13ac5f443250e82915b1d40f756130d7960 Mon Sep 17 00:00:00 2001 From: Jay DeLuca Date: Thu, 25 Jul 2024 06:01:56 -0400 Subject: [PATCH 13/13] Update java agent instrumentation disable list (#4875) --- content/en/docs/zero-code/java/agent/disable.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/content/en/docs/zero-code/java/agent/disable.md b/content/en/docs/zero-code/java/agent/disable.md index 942a6e754193..4d80c8c2fc68 100644 --- a/content/en/docs/zero-code/java/agent/disable.md +++ b/content/en/docs/zero-code/java/agent/disable.md @@ -3,7 +3,7 @@ title: Suppressing specific instrumentation linkTitle: Suppressing instrumentation weight: 11 # prettier-ignore -cSpell:ignore: akka armeria classloaders couchbase Customizer datasource dbcp Dotel dropwizard dubbo enduser finatra hikari hikaricp HSET httpasyncclient httpclient hystrix jaxrs jaxws jedis jodd kotlinx logback logmanager mojarra myfaces okhttp oshi pekko rabbitmq ratpack rediscala redisson restlet rocketmq serverlessapis spymemcached twilio vaadin vertx vibur webflux webmvc +cSpell:ignore: akka armeria classloaders clickhouse couchbase Customizer datasource dbcp Dotel dropwizard dubbo enduser finatra hikari hikaricp HSET httpasyncclient httpclient hystrix javalin jaxrs jaxws jedis jodd kotlinx ktor logback logmanager mojarra mybatis myfaces okhttp oshi pekko rabbitmq ratpack rediscala redisson restlet rocketmq serverlessapis shenyu spymemcached twilio vaadin vertx vibur webflux webmvc --- ## Disabling the agent entirely @@ -66,6 +66,7 @@ corresponding instrumentation name: {{% /config_option %}} | Apache Pekko HTTP | `pekko-http` | | Apache Pulsar | `pulsar` | | Apache RocketMQ | `rocketmq-client` | +| Apache Shenyu | `apache-shenyu` | | Apache Struts 2 | `struts` | | Apache Tapestry | `tapestry` | | Apache Tomcat | `tomcat` | @@ -75,6 +76,7 @@ corresponding instrumentation name: {{% /config_option %}} | AWS Lambda | `aws-lambda` | | AWS SDK | `aws-sdk` | | Azure SDK | `azure-core` | +| Clickhouse Client | `clickhouse` | | Couchbase | `couchbase` | | C3P0 | `c3p0` | | Dropwizard Views | `dropwizard-views` | @@ -87,10 +89,13 @@ corresponding instrumentation name: {{% /config_option %}} | Eclipse Mojarra | `jsf-mojarra` | | Eclipse Vert.x HttpClient | `vertx-http-client` | | Eclipse Vert.x Kafka Client | `vertx-kafka-client` | +| Eclipse Vert.x Redis Client | `vertx-redis-client` | | Eclipse Vert.x RxJava | `vertx-rx-java` | +| Eclipse Vert.x SQL Client | `vertx-sql-client` | | Eclipse Vert.x Web | `vertx-web` | | Elasticsearch client | `elasticsearch-transport` | | Elasticsearch REST client | `elasticsearch-rest` | +| Finagle | `finagle-http` | | Google Guava | `guava` | | Google HTTP client | `google-http-client` | | Google Web Toolkit | `gwt` | @@ -98,7 +103,9 @@ corresponding instrumentation name: {{% /config_option %}} | GraphQL Java | `graphql-java` | | GRPC | `grpc` | | Hibernate | `hibernate` | +| Hibernate Reactive | `hibernate-reactive` | | HikariCP | `hikaricp` | +| InfluxDB | `influxdb` | | Java HTTP Client | `java-http-client` | | Java `HttpURLConnection` | `http-url-connection` | | Java JDBC | `jdbc` | @@ -108,6 +115,7 @@ corresponding instrumentation name: {{% /config_option %}} | Java Servlet | `servlet` | | java.util.concurrent | `executors` | | java.util.logging | `java-util-logging` | +| Javalin | `javalin` | | JAX-RS (Client) | `jaxrs-client` | | JAX-RS (Server) | `jaxrs` | | JAX-WS | `jaxws` | @@ -117,6 +125,7 @@ corresponding instrumentation name: {{% /config_option %}} | Jodd HTTP | `jodd-http` | | JSP | `jsp` | | K8s Client | `kubernetes-client` | +| Ktor | `ktor` | | kotlinx.coroutines | `kotlinx-coroutines` | | Log4j Appender | `log4j-appender` | | Log4j MDC (1.x) | `log4j-mdc` | @@ -125,6 +134,7 @@ corresponding instrumentation name: {{% /config_option %}} | Logback MDC | `logback-mdc` | | Micrometer | `micrometer` | | MongoDB | `mongo` | +| MyBatis | `mybatis` | | Netflix Hystrix | `hystrix` | | Netty | `netty` | | OkHttp | `okhttp` | @@ -136,12 +146,14 @@ corresponding instrumentation name: {{% /config_option %}} | OSHI (Operating System and Hardware Information) | `oshi` | | Play Framework | `play` | | Play WS HTTP Client | `play-ws` | +| Quarkus | `quarkus` | | Quartz | `quartz` | | R2DBC | `r2dbc` | | RabbitMQ Client | `rabbitmq` | | Ratpack | `ratpack` | | ReactiveX RxJava | `rxjava` | | Reactor | `reactor` | +| Reactor Kafka | `reactor-kafka` | | Reactor Netty | `reactor-netty` | | Redis Jedis | `jedis` | | Redis Lettuce | `lettuce` | @@ -170,6 +182,7 @@ corresponding instrumentation name: {{% /config_option %}} | Undertow | `undertow` | | Vaadin | `vaadin` | | Vibur DBCP | `vibur-dbcp` | +| XXL-JOB | `xxl-job` | | ZIO | `zio` | **Note:** When using environment variables, dashes (`-`) should be converted to