Notas para desenvolvedores do OpenTelemetry Node.js

A instrumentação automática é um mecanismo para coletar dados de telemetria sem modificar o código-fonte do aplicativo. A instrumentação automática é um recurso fornecido pelo OpenTelemetry que permite instrumentar automaticamente seu aplicativo sem escrever código personalizado.

Utilize "detectores de recursos" adequados para melhorar a correlação entre entidades de infraestrutura utilizada no Instana. A autoinstrumentação do OpenTelemetry JavaScript deve declarar detectores de recursos para dispor de atributos de recursos suficientes. É necessário que você tenha um ` Instrumentation.js ` externo que possua detectores de recursos capazes de suportar um número suficiente de atributos de recursos. Por exemplo, é @opentelemetry/resource-detector-container necessária a versão 0.3.4 ou posterior para a ligação em um ambiente de contêiner, como um cluster do Kubernetes ou do Red Hat OpenShift. O exemplo a seguir é um Instrumentation.js utilizado na demonstração oficial do OpenTelemetry :

// Copyright The OpenTelemetry Authors
// SPDX-License-Identifier: Apache-2.0

const opentelemetry = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-grpc');
const { PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { alibabaCloudEcsDetector } = require('@opentelemetry/resource-detector-alibaba-cloud');
const { awsEc2Detector, awsEksDetector } = require('@opentelemetry/resource-detector-aws');
const { containerDetector } = require('@opentelemetry/resource-detector-container');
const { gcpDetector } = require('@opentelemetry/resource-detector-gcp');
const { envDetector, hostDetector, osDetector, processDetector } = require('@opentelemetry/resources');

const sdk = new opentelemetry.NodeSDK({
    traceExporter: new OTLPTraceExporter(),
    instrumentations: [getNodeAutoInstrumentations()],
    metricReader: new PeriodicExportingMetricReader({
        exporter: new OTLPMetricExporter(),
    }),
    resourceDetectors: [
        containerDetector,
        envDetector,
        hostDetector,
        osDetector,
        processDetector,
        alibabaCloudEcsDetector,
        awsEksDetector,
        awsEc2Detector,
        gcpDetector,
    ],
});

sdk.start();
 

A instrumentação manual envolve a criação de código personalizado para instrumentar partes específicas do seu aplicativo. Isso requer a configuração manual do código-fonte do aplicativo para configurar o OpenTelemetry SDK para receber, processar e exportar os dados de telemetria. Para obter instruções mais detalhadas, consulte o Manual de Instrumentação.

O agente do Instana pode receber diretamente traços, métricas e logs do OpenTelemetry no formato OTLP. Em seguida, o agente Instana encaminha os dados para o backend Instana. Para obter mais detalhes, consulte Enviar dados para o Agente d Instana.

É necessário especificar o endpoint do agente Instana na configuração de OTLPMetricExporter. Defina o endpoint junto com a chave ` Instana ` no formato ` JSON ` e passe-o como argumento para ` OTLPMetricExporter `, conforme mostrado no exemplo a seguir. Para mais detalhes, consulte Uso com o Node.js.

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<agent-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>'
    }
  }),
}),
 

Os dados de telemetria podem ser enviados no formato OTLP diretamente de aplicativos ou sistemas para o backend do Instana, o que também é conhecido como comunicação sem agente. Para mais detalhes, consulte “Enviar dados para o backend do Instana ”

É necessário especificar o endpoint do backend Instana na configuração de OTLPMetricExporter. Defina o endpoint juntamente com a chave Instana e os detalhes do host Instana no formato JSON e passe-os como argumento para OTLPMetricExporter, conforme mostrado no exemplo a seguir. Para mais detalhes, consulte Uso com o Node.js.

metricReader: new PeriodicExportingMetricReader({
  exporter: new OTLPMetricExporter({
    url: '<backend-otlp-endpoint>/v1/metrics', // url is optional and can be omitted - default is https://otlp-orange-saas.instana.io:4318/v1/metrics
    headers: { // an optional object containing custom headers to be sent with each request
      'x-instana-key': '<Instana key>',
      'x-instana-host': '<hostname>'
    }
  }),
}),
 

Para ativar a instrumentação automática, execute o seguinte comando para apontar para o arquivo instrumentation.js ao executar o aplicativo:

node --require ./instrumentation.js app.js
 

Para obter mais informações sobre o detector de recursos do Node.JS, consulte o opentelemetry-js-contrib.

1. Verifique os registros do agente de host em Instana para verificar se há alguma mensagem relacionada a este processo OpenTelemetry.
2. Verifique se o NodeJS foi instrumentado corretamente de forma automática ou manual.
3. Verifique se as configurações, como o endpoint e a chave ` Instana `, estão definidas corretamente no código instrumentado.