はじめに • API および SDK リファレンス

貢献 • 例

このプロジェクトについて

これは、アプリケーションからトレースとメトリックを収集するためのフレームワークであるOpenTelemetryのJavaScriptバージョンです。

クイックスタート

基本的なWebアプリケーションのトレースを設定する方法は以下のとおりです。 詳細なドキュメントについては、https://opentelemetry.io/docs/instrumentation/js/ のWebサイトを参照してください。

取り付け

NPMのタグとの依存関係は、相互に互換性がある必要があります。 詳細については、以下のバージョン互換性マトリックスを参照してください。

latest

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-node
npm install --save @opentelemetry/auto-instrumentations-node

注: は opentelemetry-js-contrib のメタパッケージで、複数の Node.js インストゥルメンテーションを初期化する簡単な方法を提供します。

auto-instrumentations-node

トレースの設定

// tracing.js

'use strict'

const process = require('process');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { ConsoleSpanExporter } = require('@opentelemetry/sdk-trace-base');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

// configure the SDK to export telemetry data to the console
// enable all auto-instrumentations from the meta package
const traceExporter = new ConsoleSpanExporter();
const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service',
  }),
  traceExporter,
  instrumentations: [getNodeAutoInstrumentations()]
});

// initialize the SDK and register with the OpenTelemetry API
// this enables the API to record telemetry
sdk.start()
  .then(() => console.log('Tracing initialized'))
  .catch((error) => console.log('Error initializing tracing', error));

// gracefully shut down the SDK on process exit
process.on('SIGTERM', () => {
  sdk.shutdown()
    .then(() => console.log('Tracing terminated'))
    .catch((error) => console.log('Error terminating tracing', error))
    .finally(() => process.exit(0));
});

アプリケーションの実行

node -r ./tracing.js app.js

上記の例では、Node.js アプリケーションに関する自動インストルメント化されたテレメトリをコンソールに出力します。より詳細な例については、入門ガイドを参照してください。自動インストゥルメンテーションの詳細については、ノード.jsアプリケーションに自動インストゥルメンテーションを提供する @opentelemetry/sdk-trace-node を参照してください。自動インストゥルメンテーションがニーズに合わない場合、または手動トレースを作成する場合は、@opentelemetry/sdk-trace-base を参照してください。

図書館著者

OpenTelemetryをライブラリに組み込もうとしているライブラリ作成者の方は、ドキュメントを参照してください。ライブラリ作成者は、パブリック API で公開されているプロパティとメソッドにのみ依存することが重要です。正式にはパブリック API の一部ではない SDK のプロパティまたはメソッドを使用する場合、アプリケーション所有者が別の SDK 実装を使用すると、ライブラリが破損する可能性があります。

サポートされているランタイム

v18

v16

v14

ノードのサポート

ノード.jsアクティブまたはメンテナンスLTSバージョンのみがサポートされています。 以前のバージョンのノードは動作する可能性がありますが、OpenTelemetryによってテストされておらず、動作が保証されていません。 OpenTelemetry Node はで導入されたモジュールに依存しており、 で起動して正しく設定されているため.JS より前のバージョンの Node v8 は動作しないことに注意してください。

v8.12.0

perf_hooks

v8.5.0

performance.timeOrigin

v8.12.0

ブラウザのサポート

自動ブラウザテストは、最新バージョンのヘッドレスChromeで実行されます。 現在、公式にサポートされているブラウザのリストはありませんが、OpenTelemetryは、幅広いサポートを備えた標準のWebテクノロジーを使用して開発されており、現在サポートされている主要なブラウザのバージョンで動作するはずです。

パッケージバージョンの互換性

OpenTelemetryは、API、安定したSDK、実験的な3つのカテゴリの個別のパッケージのセットとしてリリースされています。 API は /api にあり、安定した SDK パッケージは /packages ディレクトリにあり、実験用パッケージは /experimental/packages ディレクトリに一覧表示されます。 実験ディレクトリには、実験信号用のAPIパッケージがある場合もあります。 すべての安定版パッケージは同じバージョンでリリースされ、すべての実験的なパッケージは同じバージョンでリリースされます。 次の表では、各パッケージ セットのどのバージョンが連携して動作するかについて説明します。

バージョン管理

各パッケージの現在のバージョンは、そのモジュールのそれぞれのファイルにあります。詳細については、仕様のバージョン管理と安定性に関するドキュメントを参照してください。

package.json

機能の状態

機能サポートの詳細な内訳については、仕様コンプライアンスマトリックスを参照してください。

貢献

私たちはあなたの助けが大好きです!。タグをすぐに手に入れ、最初の問題を使用してプロジェクトを開始します。対して このプロジェクトをビルドして変更する手順については、貢献ガイドを参照してください。

毎週SIGミーティングを開催しています!会議の詳細とメモについては、コミュニティページを参照してください。

承認者 (@open-テレメトリ/js-承認者):

• ゲルハルト・シュテービッヒ、ダイナトレース
• ジョン・ブレイ、Splunk
• マーク・ピヒラー、ダイナトレース
• マーク・ウルフ、マイクロソフト
• マシューウェア、ライトステップ
• ナシームK.ウラ、トランジット
• ネビルワイリー、マイクロソフト
• オリヴィエ・アルベルティーニ、ヴィル・ド・モントリオール
• スヴェトラーナブレナン、ニューレリック

承認者ロールの詳細については、コミュニティリポジトリを参照してください。

メンテナ (@open-テレメトリ/js-メンテナ):

• アミール・ブルム、アスペクト
• チェンジョン・ウー、アリババ
• ダニエル・ディラ、ダイナトレース
• ラウノ・ビスクス、スプランク
• バレンティン・マルショー、オープンソース貢献者

メンテナロールの詳細については、コミュニティリポジトリを参照してください。

すでに貢献してくれたすべての人々に感謝します

以前のすべての承認者とメンテナに感謝します

• Bartlomiej obecny, LightStep, Maintainer
• ダニエル・カーン、ダイナトレース、メンテナ
• マユールケール、グーグル、メンテナ
• ブランドンゴンザレス、ライトステップ、承認者
• Roch Devost, DataDog, Approver

パッケージ

原薬

実装 / SDK

互換性のある輸出業者

OpenTelemetryはベンダーに依存せず、さまざまなエクスポーター実装を使用して任意のバックエンドにデータをアップロードできます。OpenTelemetryは多くのバックエンドをサポートしていますが、ベンダー/ユーザーは、プロプライエタリで非公式にサポートされているバックエンド用に独自のエクスポーターを実装することもできます。

使用可能なエクスポーターの一覧については、OpenTelemetry レジストリーを参照してください。

インストルメンテーション

OpenTelemetryは、インストゥルメンテーションを使用してトレースデータを自動的に収集できます。

このリストにないモジュールの自動トレースサポートをリクエストするには、問題を報告してください。または、ベンダー/ユーザーが自分でインストルメンテーションを記述することもできます。

現在、OpenTelemetryは以下の自動トレースをサポートしています。

ノードインストゥルメンテーション

コア

• @opentelemetry/インストルメンテーション-grpc
• @opentelemetry/instrumentation-http

コントリブ

これらのインストルメンテーションは、https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/node

ウェブインストゥルメンテーション

コア

• @opentelemetry/instrumentation-xml-http-request
• @opentelemetry/インストルメンテーションフェッチ

コントリブ

これらのインストルメンテーションは、https://github.com/open-telemetry/opentelemetry-js-contrib/tree/master/plugins/web

シム

アップグレードのガイドライン

0.28.x から 0.29.x へ

• @opentelemetry/exporter-trace-otlp-http

  の代わりにエクスポートするようになりました

  scopeSpans

  instrumentationLibrarySpans

  • このエクスポーターには、コレクターのバージョン以上が必要です。

    0.48

• @opentelemetry/exporter-metrics-otlp-http

  の代わりにエクスポートするようになりました

  scopeMetrics

  instrumentationLibraryMetrics

  • このエクスポーターには、コレクターのバージョン以上が必要です。

    0.48

0.27.x から 0.28.x へ

• In は に置き換えられます。

  @opentelemetry/exporter-trace-otlp-http

  OTLPExporterBase._isShutdown

  _shutdownOnce

0.26.x から 0.27.x

メトリックとトレースのエクスポーターは、個別のパッケージに分割されます。

• @opentelemetry/exporter-otlp-http

  =>

  @opentelemetry/exporter-trace-otlp-http

  そして

  @opentelemetry/exporter-metrics-otlp-http

• @opentelemetry/exporter-otlp-grpc

  =>

  @opentelemetry/exporter-trace-otlp-grpc

  そして

  @opentelemetry/exporter-metrics-otlp-grpc

• @opentelemetry/exporter-otlp-proto

  =>

  @opentelemetry/exporter-trace-otlp-proto

  そして

  @opentelemetry/exporter-metrics-otlp-proto

メトリックの種類の名前が変更されます。

• @openetelemetry/api-metrics

  • Meter

    • createValueRecorder

      =>

      createHistogram

    • createValueObserver

      =>

      createObservableGauge

    • createSumObserver

      =>

      createObservableCounter

    • createUpDownSumObserver

      =>

      createObservableUpDownCounter

  • ValueRecorder

    =>

    Histogram

  • ValueObserver

    =>

    ObservableGauge

  • SumObserver

    =>

    ObservableCounter

  • UpDownSumObserver

    =>

    ObservableUpDownCounter

  • ObserverResult

    =>

    ObservableResult

  • Observation.observer

    =>

    Observation.observable

• @opentelemetry/sdk-metrics-base

  • MetricKind

    • VALUE_RECORDER

      =>

      HISTOGRAM

    • SUM_OBSERVER

      =>

      OBSERVABLE_COUNTER

    • UP_DOWN_SUM_OBSERVER

      =>

      OBSERVABLE_UP_DOWN_COUNTER

    • VALUE_OBSERVER

      =>

      OBSERVABLE_GAUGE

0.25.x から 1.x.y

コレクター・エクスポーター・パッケージとタイプの名前が変更されます。

• @opentelemetry/exporter-collector

  =>

  @opentelemetry/exporter-otlp-http

  • CollectorExporterBase

    =>

    OTLPExporterBase

  • CollectorTraceExporter

    =>

    OTLPTraceExporter

  • CollectorMetricExporter

    =>

    OTLPMetricExporter

  • CollectorExporterBrowserBase

    =>

    OTLPExporterBrowserBase

  • CollectorExporterNodeBase

    =>

    OTLPExporterNodeBase

  • CollectorExporterConfigBase

    =>

    OTLPExporterConfigBase

  • CollectorExporterError

    =>

    OTLPExporterError

  • COLLECTOR_SPAN_KIND_MAPPING

    =>

    OTLP_SPAN_KIND_MAPPING

  • collectorTypes

    =>

    otlpTypes

• @opentelemetry/exporter-collector-grpc

  =>

  @opentelemetry/exporter-otlp-grpc

  • CollectorTraceExporter

    =>

    OTLPTraceExporter

  • CollectorMetricExporter

    =>

    OTLPMetricExporter

  • CollectorExporterConfigNode

    =>

    OTLPExporterConfigNode

• @opentelemetry/exporter-collector-proto

  =>

  @opentelemetry/exporter-otlp-proto

  • CollectorExporterNodeBase

    =>

    OTLPExporterNodeBase

  • CollectorMetricExporter

    =>

    OTLPMetricExporter

  • CollectorTraceExporter

    =>

    OTLPTraceExporter

• @opentelemetry/コアのW3Cプロパゲータの名前が変更されました

  • HttpTraceContextPropagator

    ->

    W3CTraceContextPropagator

  • HttpBaggagePropagator

    ->

    W3CBaggagePropagator

0.24.x から 0.25.x へ

• トレースとメトリクスの SDK パッケージの名前が変更され、一貫性のある名前付けスキーマを持つようになりました。
  • @opentelemetry/トレース-> @opentelemetry/SDK トレースベース
  • @opentelemetry/ノード-> @opentelemetry/SDK トレースノード
  • @opentelemetry/ウェブ -> @opentelemetry/SDK-トレースウェブ
  • @opentelemetry/メトリクス-> @opentelemetry/SDK メトリクスベース
  • @opentelemetry/node-sdk -> @opentelemetry/sdk-node

0.23.x to 0.24.x

• ResourceAttributes

  renamed to in the package

  SemanticResourceAttributes

  @opentelemetry/semantic-conventions

0.19.x to 0.20.0

• HttpBaggage

  renamed to

  HttpBaggagePropagator

• HttpTraceContext

  renamed to

  HttpTraceContextPropagator

• JaegerHttpTracePropagator

  renamed to

  JaegerPropagator

• serviceName

  configuration removed from Collector exporters. Use Resource attribute instead.

  service.name

• Prometheus exporter added suffix to counter metrics.

  _total

0.18.x to 0.19.0

• API is now a peer dependency. This means that users will need to include as a dependency of their project in order to use the SDK. NPM version 7+ (Node 15+) should do this automatically.

  @opentelemetry/api

• All plugins have been removed in favor of instrumentations.

• The package previously exported three propagators: ,, and , but now only exports the . It extracts b3 context in single and multi-header encodings, and injects context using the single-header encoding by default, but can be configured to inject context using the multi-header endcoding during construction: . If you were previously using the or directly, you should update your code to use the with the appropriate configuration. See the readme for full details and usage.

  @opentelemetry/propagator-b3

  B3Propagator

  B3SinglePropagator

  B3MultiPropagator

  B3Propagator

  new B3Propagator({ injectEncoding: B3InjectEncoding.MULTI_HEADER })

  B3SinglePropagator

  B3MultiPropagator

  B3Propagator

• Sampling configuration via environment variable has changed. If you were using then you should replace it with and where is a number in the [0..1] range, e.g. "0.25". Default is 1.0 if unset.

  OTEL_SAMPLING_PROBABILITY

  OTEL_TRACES_SAMPLER=parentbased_traceidratio

  OTEL_TRACES_SAMPLER_ARG=<number>

  <number>

0.17.0 to 0.18.0

• diag.setLogLevel

  is removed and LogLevel can be set by an optional second parameter to

  setLogger

PR-1975

• Breaking change - The resulting resource MUST have all attributes that are on any of the two input resources. If a key exists on both the old and updating resource, the value of the updating resource MUST be picked - previously it was opposite.

0.16.0 to 0.17.0

PR-1880 feat(diag-logger): introduce a new global level api.diag for internal diagnostic logging

PR-1925 feat(diag-logger): part 2 - breaking changes - remove api.Logger, api.NoopLogger, core.LogLevel, core.ConsoleLogger

• These PR's remove the previous and implementations and change the way you should use the replacement and , below are simple examples of how to change your existing usages.

  Logger

  LogLevel

  DiagLogger

  DiagLogLevel

Setting the global diagnostic logger

The new global

api.diag

setLogger()

setLogLevel()

DiagLogger

All included logger references have been removed in preference to using the global directly, so you no longer need to pass around the logger instance via function parameters or included as part of the configuration for a component.

api.diag

import { diag, DiagConsoleLogger, DiagLogLevel } from "@opentelemetry/api";
// Setting the default Global logger to use the Console
// And optionally change the logging level (Defaults to INFO)
diag.setLogger(new DiagConsoleLogger(), DiagLogLevel.ERROR)

Using the logger anywhere in the code

import { diag } from "@opentelemetry/api";

// Remove or make optional the parameter and don't use it.
export function MyFunction() {
  diag.debug("...");
  diag.info("...");
  diag.warn("...");
  diag.error("...");
  diag.verbose("..");
}

Setting the logger back to a noop

import { diag } from "@opentelemetry/api";
diag.setLogger();

PR-1855 Use instrumentation loader to load plugins and instrumentations

• Providers do no load the plugins anymore. Also PluginLoader has been removed from providers, use instead

  registerInstrumentations

//Previously in node
const provider = new NodeTracerProvider({
  plugins: {
    '@grpc/grpc-js': {
      enabled: true,
      path: '@opentelemetry/plugin-grpc-js',
    },
  }
});

// Now
const provider = new NodeTracerProvider();
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
registerInstrumentations({
  instrumentations: [
    {
      plugins: {
        '@grpc/grpc-js': {
          enabled: true,
          path: '@opentelemetry/plugin-grpc-js',
        },
      }
    }
  ],
  tracerProvider: provider,
});

// or if you want to load only default instrumentations / plugins
registerInstrumentations({
  tracerProvider: provider,
});

//Previously in browser
const provider = new WebTracerProvider({
  plugins: [
    new DocumentLoad()
  ]
});
// Now
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const provider = new WebTracerProvider();
registerInstrumentations({
  instrumentations: [
    new DocumentLoad(),
  ],
});

• registerInstrumentations

  supports loading old plugins and instrumentations together. It also supports setting tracer provider and meter provider on instrumentations

PR-1874 More specific API type names

Some types exported from have been changed to be more specific.

"@opentelemetry/api"

• AttributeValue

  renamed to

  SpanAttributeValue

• Attributes

  renamed to

  SpanAttributes

• EntryTtl

  renamed to

  BaggageEntryTtl

• EntryValue

  renamed to

  BaggageEntryValue

• Status

  renamed to

  SpanStatus

• StatusCode

  renamed to

  SpanStatusCode

0.15.0 to 0.16.0

PR-1863 removed public attributes and from nodejs and

keepAlive

httpAgentOptions

CollectorTraceExporter

CollectorMetricExporter

0.14.0 to 0.15.0

PR-1764 では、以下からいくつかの API が削除されました。

Tracer

• Tracer.getCurrentSpan()

  ：使う

  api.getSpan(api.context.active())

• Tracer.withSpan(span)

  ：使う

  api.context.with(api.setSpan(api.context.active(), span))

• Tracer.bind(target)

  ：使う

  api.context.bind(target)

PR-1797 雑用: メトリックを独自の API パッケージに分割します。

• への参照は次のように変更する必要があります

  require("@opentelemetry/api").metrics

  require("@opentelemetry/api-metrics").metrics

PR-1725新しい gRPC の既定のポートを使用する

• で使用されるデフォルトのポートが to に変更されます。

  @opentelemetry/exporter-collector-grpc

  55680

  4317

PR-1749 雑用: スパン関連のコンテキスト API の命名を改善

• 名前を に変更

  [gs]etActiveSpan()

  [gs]etSpan()

• 名前を に変更

  setExtractedSpanContext()

  setSpanContext()

• 名前を に変更

  getParentSpanContext()

  getSpanContext()

お役立ちリンク

• OpenTelemetryの詳細については、以下をご覧ください https://opentelemetry.io/
• このプロジェクトに関するヘルプやフィードバックについては、GitHub ディスカッションに参加してください。

ライセンス

Apache 2.0 - 詳細については、ライセンス を参照してください。