Le Blog Amazon Web Services
Exportation de métriques OpenTelemetry depuis AWS Lambda vers OpenSearch
Cet article a été co-écrit avec Nathan Agez, Lead Software Engineer chez TrackIt
Les organisations ont besoin d’approches flexibles pour collecter et analyser les données de télémétrie de leurs applications. De nombreuses équipes nécessitent la capacité d’envoyer des métriques, des traces et des journaux depuis les fonctions AWS Lambda vers des plateformes d’observabilité centralisées au-delà d’Amazon CloudWatch. Cette capacité permet des analyses avancées, la corrélation multi-environnement et l’intégration avec l’infrastructure de surveillance existante.
Cet article démontre comment vous pouvez instrumenter des fonctions AWS Lambda avec des métriques personnalisées OpenTelemetry et les exporter vers Amazon OpenSearch Serverless. La solution utilise AWS Distro for OpenTelemetry (ADOT) Lambda layers et Amazon OpenSearch Ingestion. OpenTelemetry fournit une norme neutre vis-à-vis des providers pour collecter des métriques, des traces et des journaux depuis vos applications.
L’architecture repose sur trois composants principaux. Le layer ADOT Lambda fournit un collecteur OpenTelemetry intégré dans l’environnement d’exécution Lambda. Amazon OpenSearch Ingestion agit comme un point de terminaison OTLP managé et un pipeline de données. Amazon OpenSearch Serverless stocke les données de métriques de séries temporelles avec rotation automatique des index. Cette approche vous donne la flexibilité d’exporter la télémétrie vers des backends alternatifs tout en maintenant la compatibilité avec la norme OpenTelemetry.
Vous pouvez suivre les métriques métier personnalisées important à votre organisation. Suivre les commandes traitées, les échecs de paiement ou la latence d’inférence d’apprentissage automatique. Instrumenter ces métriques directement dans vos fonctions Lambda.
Fonctionnement des couches ADOT Lambda
Le layer ADOT Lambda encapsule le SDK OpenTelemetry et un collecteur intégré. Alors que les architectures traditionnelles nécessitent une infrastructure de collecteur séparée que vous devez gérer et dimensionner. Le layer ADOT intègre le collecteur directement dans le runtime Lambda lui-même. Cette conception offre une expérience d’instrumentation plus simple sans infrastructure supplémentaire.
Le layer comprend plusieurs composants qui fonctionnent ensemble. Le SDK et l’API OpenTelemetry fournissent la fonctionnalité de base pour créer et gérer les données de télémétrie. Les bibliothèques d’auto-instrumentation prennent en charge les runtimes Node.js, Python, Java et .NET. Un collecteur intégré regroupe et exporte la télémétrie vers la destination de votre choix. Des exporters préconfigurés permettent l’intégration avec AWS X-Ray et Amazon CloudWatch.
Le collecteur intégré s’exécute dans le cadre du cycle de vie d’invocation Lambda. Vous n’avez pas besoin de conteneurs sidecar ou de flottes de collecteurs externes. Cette architecture réduit la maintenance opérationnelle nécessaire pour gérer une infrastructure de collecteur dédiée. Alors que vous maintenez la flexibilité du protocole OpenTelemetry.
Configuration de l’infrastructure
Collection OpenSearch Serverless
Amazon OpenSearch Serverless fournit une couche de stockage sans serveur pour les données de métriques de séries temporelles. Le service se dimensionne automatiquement en fonction de votre charge de travail. Vous avez besoin de trois politiques de sécurité pour configurer une collection : chiffrement, accès réseau et accès aux données.
Le modèle CloudFormation suivant crée une collection OpenSearch Serverless :
Resources:
MetricsCollection:
Type: AWS::OpenSearchServerless::Collection
DependsOn:
- EncryptionPolicy
- NetworkPolicy
Properties:
Name: !Sub 'metrics-${Environment}'
Type: VECTORSEARCH
StandbyReplicas: DISABLED
EncryptionPolicy:
Type: AWS::OpenSearchServerless::SecurityPolicy
Properties:
Name: !Sub 'metrics-encryption-${Environment}'
Type: encryption
Policy: !Sub >-
{"Rules":[{"ResourceType":"collection","Resource":["collection/metrics-${Environment}"]}],"AWSOwnedKey":true}
NetworkPolicy:
Type: AWS::OpenSearchServerless::SecurityPolicy
Properties:
Name: !Sub 'metrics-network-${Environment}'
Type: network
Policy: !Sub >-
[{"Rules":[{"ResourceType":"collection","Resource":["collection/metrics-${Environment}"]},{"ResourceType":"dashboard","Resource":["collection/metrics-${Environment}"]}],"AllowFromPublic":true}]
Pour les déploiements en production, restreignez la NetworkPolicy à des VPC spécifiques ou à des points de terminaison VPC plutôt que d’autoriser l’accès public. Cette configuration améliore la sécurité en limitant l’accès à vos données de métriques.
Pipeline OpenSearch Ingestion
Amazon OpenSearch Ingestion fournit un point de terminaison d’ingestion géré compatible OpenTelemetry. Le pipeline reçoit des métriques au format OTLP, les traite et les écrit dans Amazon OpenSearch avec gestion automatique des index.
La configuration suivante crée un pipeline avec un index :
OSISPipeline:
Type: AWS::OSIS::Pipeline
Properties:
PipelineName: !Sub 'metrics-pipeline-${Environment}'
MinUnits: 1
MaxUnits: 1
PipelineConfigurationBody: !Sub |
version: '2'
otel-metrics-pipeline:
source:
otel_metrics_source:
path: '/v1/metrics'
processor:
- otel_metrics: null
sink:
- opensearch:
hosts:
- ${MetricsCollection.CollectionEndpoint}
aws:
serverless: true
region: ${AWS::Region}
index_type: custom
index: metrics-%{MM-yyyy}
Le modèle d’index metrics-%{MM-yyyy} crée des index partitionnés dans le temps tels que metrics-01-2026 et metrics-02-2026. Cette approche permet des requêtes efficaces sur les données récentes. Vous pouvez gérer la rétention en supprimant les anciens index. Les index partitionnés dans le temps aident également à optimiser les coûts de stockage en supprimant les données historiques dont vous n’avez plus besoin.
Configuration de la fonction Lambda
Ajout de la couche ADOT
AWS distribue le layer ADOT Lambda via des layers Lambda managés par AWS. Les numéros de version et les formats d’ARN varient selon la région et le runtime. Les layers Lambda sont des ressources régionales que vous ne pouvez utiliser que dans la région où elles sont publiées.
Globals:
Function:
Timeout: 60
Layers:
- !Sub arn:aws:lambda:${AWS::Region}:901920570463:layer:aws-otel-nodejs-amd64-ver-1-30-2:1
Environment:
Variables:
AWS_LAMBDA_EXEC_WRAPPER: /opt/otel-handler
OPENTELEMETRY_COLLECTOR_CONFIG_URI: s3://your-config-bucket/collector-config.yamlUtilisez amd64 comme architecture pour les processeurs basés sur x86. Deux variables d’environnement sont critiques pour un fonctionnement correct. La variable AWS_LAMBDA_EXEC_WRAPPER avec la valeur /opt/otel-handler active le script wrapper qui initialise le SDK OpenTelemetry avant l’exécution de votre handler. La variable OPENTELEMETRY_COLLECTOR_CONFIG_URI pointe vers l’emplacement du fichier de configuration du collecteur.
Auto-instrumentation
Le layer ADOT fournit une instrumentation automatique pour les bibliothèques courantes sans modifications de code. Pour les runtimes Node.js, cela inclut les clients HTTP et HTTPS, les appels AWS SDK et les clients de base de données. Vous pouvez contrôler quels modules d’instrumentation sont actifs.
La configuration suivante montre comment contrôler l’auto-instrumentation :
Environment:
Variables:
OTEL_NODE_ENABLED_INSTRUMENTATIONS: http,aws-sdk
# Or disable specific instrumentations:
OTEL_NODE_DISABLED_INSTRUMENTATIONS: fs
L’auto-instrumentation capture automatiquement les traces distribuées et les métriques de base. Le système enregistre le nombre et la durée des requêtes HTTP sans code supplémentaire. Cependant, vous devez utiliser l’API Metrics OpenTelemetry pour capturer les métriques métier spécifiques qui importent à votre application.
Configuration du collecteur
Le collecteur intégré nécessite un fichier de configuration externe qui spécifie les « receivers », les « processors » et les « exporters ». Le layer ADOT Lambda prent en charge plusieurs fournisseurs de configuration, notamment fichier, env, yaml, http, https et s3.
#Collector-config.yaml
extensions:
sigv4auth:
region: 'us-west-2'
service: 'osis'
receivers:
otlp:
protocols:
grpc:
http:
exporters:
otlphttp:
metrics_endpoint: 'osis-endpoint'
auth:
authenticator: sigv4auth
compression: none
service:
extensions: [sigv4auth]
pipelines:
metrics:
receivers: [otlp]
exporters: [otlphttp]
Ce fichier configure le collecteur pour recevoir les métriques OTLP et les exporter vers Amazon OpenSearch Ingestion. L’extension sigv4auth gère automatiquement l’authentification AWS.
Implémentation de métriques personnalisées
L’auto-instrumentation fournit une observabilité de base pour vos fonctions Lambda. Les métriques critiques pour l’entreprise nécessitent une instrumentation manuelle utilisant l’API Metrics OpenTelemetry. Vous devez installer le package API en tant que dépendance.
npm install @opentelemetry/apiLe package @opentelemetry/api fournit l’API publique. Le layer ADOT fournit l’implémentation du SDK. Vous n’avez besoin d’inclure que le package API comme dépendance dans votre code d’application.
Code d’instrumentation
L’exemple TypeScript suivant montre comment créer et enregistrer des métriques personnalisées :
import { metrics } from '@opentelemetry/api';
import { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
// Obtain a Meter instance (scoped by service name and version)
const meter = metrics.getMeter('video-service', '1.0.0');
// Define metrics at module scope to avoid recreation on each invocation
const requestCounter = meter.createCounter('api.requests', {
description: 'Total API requests',
unit: '1',
});
const requestDuration = meter.createHistogram('api.request.duration', {
description: 'API request duration',
unit: 'ms',
});
export async function handler(
event: APIGatewayProxyEventV2
): Promise<APIGatewayProxyResultV2> {
const startTime = Date.now();
const endpoint = event.routeKey;
requestCounter.add(1, {
'http.method': event.requestContext.http.method,
'http.route': endpoint,
});
try {
// Business logic
const result = await processRequest(event);
const duration = Date.now() - startTime;
requestDuration.record(duration, {
'http.route': endpoint,
'http.status_code': 200,
});
return {
statusCode: 200,
body: JSON.stringify(result),
};
} catch (error) {
const duration = Date.now() - startTime;
requestDuration.record(duration, {
'http.route': endpoint,
'http.status_code': 500,
'error.type': error.constructor.name,
});
requestCounter.add(1, {
'http.method': event.requestContext.http.method,
'http.route': endpoint,
'error': 'true',
});
return {
statusCode: 500,
body: JSON.stringify({ error: 'Internal server error' }),
};
}
}
Ce code obtient une instance Meter délimitée par le nom et la version du service. Définissez les métriques au niveau du module pour éviter la recréation à chaque invocation. Cette approche améliore les performances et réduit l’allocation de mémoire. L’exemple crée un compteur pour le total des requêtes et un histogramme pour la durée des requêtes. Chaque métrique inclut des attributs qui fournissent un contexte tel que la méthode HTTP, la route et le code de statut.
Accès aux données et permissions
Amazon OpenSearch Ingestion nécessite des permissions d’écriture sur la collection Amazon OpenSearch Serverless. Le template CloudFormation suivant crée la politique d’accès aux données nécessaire :
DataAccessPolicy:
Type: AWS::OpenSearchServerless::AccessPolicy
Properties:
Name: !Sub 'metrics-access-${Environment}'
Type: data
Policy: !Sub |
[{
"Rules": [{
"ResourceType": "collection",
"Resource": ["collection/metrics-${Environment}"],
"Permission": ["aoss:CreateCollectionItems", "aoss:UpdateCollectionItems"]
}, {
"ResourceType": "index",
"Resource": ["index/metrics-${Environment}/*"],
"Permission": ["aoss:CreateIndex", "aoss:WriteDocument", "aoss:ReadDocument"]
}],
"Principal": ["${OSISRole.Arn}"]
}]Vos fonctions Lambda n’accèdent pas directement à Amazon OpenSearch Serverless. Les métriques transitent par Amazon OpenSearch Ingestion, qui gère l’authentification et l’autorisation en votre nom.
Conclusion
Cette architecture montre comment vous pouvez combiner l’instrumentation OpenTelemetry avec les services managés AWS pour construire une solution d’observabilité flexible. La couche ADOT Lambda élimine le besoin de gérer une infrastructure de collecteur dédiée tout en maintenant la compatibilité du protocole avec n’importe quel backend compatible OpenTelemetry.
Vous obtenez plusieurs avantages avec cette approche. Votre code d’instrumentation OpenTelemetry fonctionne avec n’importe quel backend conforme tel qu’OpenSearch, Prometheus, Grafana ou Datadog. Le collecteur intégré élimine la charge opérationnelle car vous n’avez pas besoin de provisionner ou de gérer une infrastructure séparée. OpenTelemetry est une norme de la Cloud Native Computing Foundation pour l’observabilité. Vous pouvez changer d’exportateurs sans modifier votre code d’application. Cela vous donne de la flexibilité au fur et à mesure que vos besoins évoluent.
Ce modèle fournit une base pour construire des solutions d’observabilité qui s’étendent sur plusieurs fournisseurs cloud. Vous pouvez migrer progressivement des SDK spécifiques aux fournisseurs vers OpenTelemetry tout en maintenant la compatibilité avec vos plateformes d’observabilité existantes. L’approche neutre vis-à-vis des fournisseurs vous aide à éviter le verrouillage et vous donne la liberté de choisir les outils qui fonctionnent pour votre organisation.