OpenTelemetry Integration for Node.js 應用程式

無伺服器 OpenTelemetry Exporter

套件 @instana/opentelemetry-exporter 提供 OpenTelemetry exporter ，可將 OpenTelemetry 跨距轉換並傳送至 Instana 後端。

Instana Node.js OpenTelemetry 匯出器主要設計用於在無伺服器環境中使用，例如 AWS Lambda 或 AWS Fargate。 Instana 已透過主機代理程式提供 OpenTelemetry for SaaS 及自行管理解決方案的支援。 不過，如果您的 Node.js 應用程式在無伺服器環境中執行 (代理程式不存在) ，則無伺服器 OpenTelemetry 匯出器是要執行的方法。

若要使用匯出器，請將套件安裝至專案，將套件匯入至追蹤模組，並建立新的 InstanaExporter實例。

匯出器預期必須提供兩個 Instana 環境變數 給應用程式:

• INSTANA_AGENT_KEY
• INSTANA_ENDPOINT_URL

或者，您可以提供這些值作為建構子的引數，但不建議使用此替代方案，因為這是您可能想要避免公開的機密資料。

例如，您可以將匯出器配置到追蹤模組中，如下所示:

'use strict';

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

// Require the Instana OpenTelemetry Exporter
const { InstanaExporter } = require('@instana/opentelemetry-exporter');

// Instantiate the Instana Exporter.
// Make sure to provide the agent key and the serverless endpoint URL via the following environment variables:
// * INSTANA_AGENT_KEY
// * INSTANA_ENDPOINT_URL
const instanaTraceExporter = new InstanaExporter();

/*
 * If you have not provided the agent key and the serverless endpoint URL via environment variables:
 * const instanaTraceExporter = new InstanaExporter({ agentKey: 'agent_key', endpointUrl: 'endpoint_url' });
 */

const nodeAutoInstrumentations = getNodeAutoInstrumentations();

const sdk = new opentelemetry.NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service'
  }),
  // Configure OpenTelemetry to use the Instana Exporter
  traceExporter: instanaTraceExporter,
  instrumentations: [nodeAutoInstrumentations]
});

sdk.start()
...

當 OpenTelemetry 所監視的應用程式執行時， Instana 匯出程式會將 OpenTelemetry 跨距轉換為 Instana 跨距，並將它們傳送至後端端點。

OpenTelemetry 追蹤視覺化將呈現在 Instana 使用者介面中，就像一般 Instana 追蹤跨距一樣。

OpenTelemetry 傳播器

OpenTelemetry 環境定義傳播器套件 @opentelemetry/propagator-instana 會將專有 Instana 追蹤相關性標頭轉換成 OpenTelemetry 追蹤環境定義，反之亦然。 如需 OpenTelemetry 環境定義傳播器的一般資訊，請參閱 OpenTelemetry 傳播器 。

使用 npm install --save @opentelemetry/propagator-instana來安裝套件，並將下列程式碼新增至廣域追蹤器配置檔:

const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { InstanaPropagator } = require('@opentelemetry/propagator-instana');
// ...

const provider = new NodeTracerProvider();

provider.register({
  propagator: new InstanaPropagator()
});

OpenTelemetry 取樣器

除非追蹤環境定義中 sampled 旗標的值為 false，否則 OpenTelemetry 取樣器套件 @instana/opentelememetry-sampler 會置換預設 OpenTelemetry 取樣行為，以便對任何要求進行取樣。 如需 OpenTelemetry 範例程式的一般資訊，請參閱 OpenTelemetry 範例程式 。

取樣器需要與套件 `@opentelemetry/propagator-instana 一起使用。

使用指令 npm install --save @opentelemetry/propagator-instana @instana/opentelemetry-sampler來安裝這兩個套件，並將下列程式碼新增至廣域追蹤器配置檔:

const api = require('@opentelemetry/api');
const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
const { Resource } = require('@opentelemetry/resources');
const { InstanaAlwaysOnSampler } = require('@instana/opentelemetry-sampler');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { InstanaPropagator } = require('@opentelemetry/propagator-instana');

const nodeAutoInstrumentations = getNodeAutoInstrumentations();
api.propagation.setGlobalPropagator(new InstanaPropagator());

const traceOtlpExporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
});

const sdk = new opentelemetry.NodeSDK({
  traceExporter: traceOtlpExporter,
  instrumentations: [nodeAutoInstrumentations],
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'my-service'
  }),
  sampler: new InstanaAlwaysOnSampler()
});

sdk
  .start()
  .then(() => console.log('Tracing initialized'))
  .catch(err => console.log('Error initializing tracing', err));

OpenTelemetry 資源偵測器

附註: Instana OpenTelemetry 資源偵測器一律需要 Instana 代理程式部署並在相同主機上執行。

OpenTelemetry 資源偵測器套件 @opentelemetry/resource-偵測器-instana 可利用其他資源屬性來強化 OpenTelemetry 追蹤資訊。 如需 OpenTelemetry 資源偵測器的一般資訊，請參閱 OpenTelemetry 資源偵測器 。

使用指令 npm install --save @opentelemetry/resource-detector-instana安裝套件，並將下列程式碼新增至廣域追蹤器配置檔:

import {
  Resource,
  processDetector,
  envDetector,
} from "@opentelemetry/resources";
import { SemanticResourceAttributes } from "@opentelemetry/semantic-conventions";
import { NodeSDK } from "@opentelemetry/sdk-node";
import { instanaAgentDetector } from "@opentelemetry/resource-detector-instana";

const globalResource = new Resource({
   [SemanticResourceAttributes.SERVICE_NAME]: "TestService",
});

const sdk = new NodeSDK({
   resourceDetectors: [envDetector, processDetector, instanaAgentDetector]
   resource: globalResource,
});

sdk.start()

此外，還可以提供下列環境變數:

• INSTANA_AGENT_HOST:Instana 代理程式主機名稱 (預設值: localhost)
• INSTANA_AGENT_PORT:Instana 代理程式埠 (預設值: 42699)
• INSTANA_RETRY_TIMEOUT_MS: 資源偵測器執行三次重試，以連接至 Instana 代理程式。 這是重試之間的逾時值 (預設值: 1000)
• INSTANA_AGENT_TIMEOUT_MS: 連接至 Instana 代理程式時，用戶端逾時 (預設值: 3000)