Migração de SDKs do Elastic

Migração de SDKs do Elastic

O Elastic Stack oferece dois tipos de SDKs de linguagem para instrumentar aplicações:

1. agentes oficiais de APM da Elastic – Eles são desenvolvidos especificamente para uso com o Elastic Stack. No momento, não há um caminho de migração direto para esses SDKs. As aplicações que os utilizam precisarão ser instrumentadas novamente com os SDKs do ClickStack correspondentes.

2. Elastic Distributions of OpenTelemetry (EDOT SDKs) – Essas são as distribuições da Elastic dos SDKs padrão do OpenTelemetry, disponíveis para .NET, Java, Node.js, PHP e Python. Se a sua aplicação já usa um SDK do EDOT, não será necessário instrumentar o código novamente. Em vez disso, basta reconfigurar o SDK para exportar dados de telemetria para o OTLP Collector incluído no ClickStack. Consulte “Migrando SDKs do EDOT” para mais detalhes.

Use os SDKs do ClickStack sempre que possível

Embora os SDKs padrão do OpenTelemetry sejam compatíveis, recomendamos fortemente o uso dos SDKs distribuídos pelo ClickStack para cada linguagem. Essas distribuições incluem instrumentação adicional, configurações padrão aprimoradas e extensões personalizadas projetadas para funcionar perfeitamente com o pipeline e a UI do ClickStack. Ao usar os SDKs do ClickStack, você pode habilitar recursos avançados, como stack traces de exceções, que não estão disponíveis no OpenTelemetry puro nem nos SDKs do EDOT.

​

Migrando SDKs do EDOT

Assim como os SDKs do ClickStack baseados em OpenTelemetry, as Elastic Distributions of the OpenTelemetry SDKs (SDKs do EDOT) são versões personalizadas dos SDKs oficiais do OpenTelemetry. Por exemplo, o EDOT Python SDK é uma distribuição personalizada pelo fornecedor do OpenTelemetry Python SDK projetada para funcionar perfeitamente com o Elastic Observability.

Como esses SDKs são baseados em bibliotecas padrão do OpenTelemetry, a migração para o ClickStack é simples — não é necessário reinstrumentar a aplicação. Basta ajustar a configuração para direcionar os dados de telemetria para o ClickStack OpenTelemetry Collector.

A configuração segue os mecanismos padrão do OpenTelemetry. Em Python, isso normalmente é feito por meio de variáveis de ambiente, conforme descrito na documentação de instrumentação sem código do OpenTelemetry.

Uma configuração típica do SDK do EDOT pode ser assim:

export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
export OTEL_EXPORTER_OTLP_ENDPOINT=https://my-deployment.ingest.us-west1.gcp.cloud.es.io
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=ApiKey P....l"

Para migrar para o ClickStack, atualize o endpoint para apontar para o OTLP Collector local e altere o cabeçalho de autorização:

export OTEL_RESOURCE_ATTRIBUTES=service.name=<app-name>
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_HEADERS="authorization=<YOUR_INGESTION_API_KEY>"

Sua API key de ingestão é gerada pelo aplicativo HyperDX e pode ser encontrada em Team Settings → API Keys.