opentelemetry-js - OpenTelemetry JavaScript Client

(OpenTelemetry JavaScript Client)

Created at: 2019-05-10 10:01:43
Language: TypeScript
License: Apache-2.0

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

GitHub リリース (プレリリースを含む最新の日付) コーデックステータス ライセンス
ビルドステータス Beta

貢献


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

これは、アプリケーションからトレースとメトリックを収集するためのフレームワークである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 実装を使用すると、ライブラリが破損する可能性があります。

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

プラットフォームバージョン サポート
ノード.JS
v18
ノード.JS
v16
ノード.JS
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パッケージがある場合もあります。 すべての安定版パッケージは同じバージョンでリリースされ、すべての実験的なパッケージは同じバージョンでリリースされます。 次の表では、各パッケージ セットのどのバージョンが連携して動作するかについて説明します。

原薬 安定したパッケージ 実験パッケージ
1.3.x 1.8.x 0.34.x
1.2.x 1.7.x 0.33.x
1.2.x 1.6.x 0.32.x
1.1.x 1.5.x 0.31.x
1.1.x 1.4.x 0.30.x
1.1.x 1.3.x 0.29.x
1.1.x 1.2.x 0.29.x
1.1.x 1.1.x 0.28.x
1.0.x 1.0.x 0.27.x
1.0.x 1.0.x 0.26.x

バージョン管理

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

package.json

機能の状態

信号 API ステータス SDK ステータス
トレーシング
メトリック
ログ 発達 発達

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

貢献

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

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

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

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

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

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

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

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

パッケージ

原薬

パッケージ 形容
@opentelemetry/API 本パッケージは、OpenTelemetryコアトレースおよびメトリクスモデル用のTypeScriptインタフェース、列挙型、およびno-op実装を提供します。これは、サーバーとブラウザーの両方での使用を目的としています。
@opentelemetry/コア 本パッケージは、トレースとメトリクスのための OpenTelemetry API のデフォルトおよびノーオペレーション実装を提供します。これは、サーバーとブラウザーの両方での使用を目的としています。

実装 / SDK

パッケージ 形容
@opentelemetry/SDK トレースベース このモジュールは、インストルメンテーションとスパンの作成を完全に制御します。デフォルトでは、async_hooksやインストルメンテーションは読み込まれません。これは、サーバーとブラウザーの両方での使用を目的としています。
@opentelemetry/SDK メトリクス このモジュールは、時系列データを報告するための機器とメーターを提供します。
@opentelemetry/SDK トレースノード このモジュールは、Node.jsアプリケーションの自動トレースを提供します。これは、サーバー上でのみ使用することを目的としています。
@opentelemetry/SDK-トレースウェブ このモジュールは、Webアプリケーションの自動インストルメンテーションとトレースを提供します。これは、ブラウザでの使用のみを目的としています。

互換性のある輸出業者

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

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

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

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

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

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

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

コア
コントリブ

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

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

コア
コントリブ

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

シム

パッケージ 形容
@opentelemetry/shim オープントレース OpenTracing shim により、既存の OpenTracing インストゥルメンテーションが OpenTelemetryにレポートできるようになります。

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

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
provides the ability to set the global diagnostic logger and logging level , it is also a implementation and should be directly to log diagnostic messages.
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()

お役立ちリンク

ライセンス

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