Esta página está diseñada para desarrolladores de aplicaciones que deseen recopilar datos de Cloud Trace para aplicaciones de Node.js mediante OpenTelemetry. OpenTelemetry es un framework de instrumentación independiente del proveedor que puedes usar para recopilar datos de seguimiento y de métricas. Para obtener información sobre cómo instrumentar tu código, consulta Instrumentación y observabilidad.
- Instala los paquetes de OpenTelemetry.
- Configura la aplicación para exportar intervalos a Cloud Trace.
- Configura tu plataforma.
Para obtener información de la versión, consulta lo siguiente:
Para obtener contenido de referencia de OpenTelemetry, consulta lo siguiente:
Si deseas obtener los detalles más recientes sobre OpenTelemetry para Node.js, junto con documentación y ejemplos adicionales, consulta OpenTelemetry.
Antes de comenzar
-
En el panel de navegación de la consola de Google Cloud, selecciona APIs y servicios, haz clic en Habilitar APIs y servicios y, luego, habilita la API de Cloud Trace:
Si aparece API habilitada, la API ya está habilitada. De lo contrario, haz clic en el botón Habilitar.
Instala, inicializa y usa el cliente
OpenTelemetry ofrece las siguientes formas de instrumentar tu aplicación:
Instrumentación automática para aplicaciones de Node.js
Cuando usas este enfoque, configuras tu aplicación para que incluya el SDK de
@opentelemetry/sdk-trace-node
. Sin embargo, no es necesario que realices cambios en el código de ninguna de las bibliotecas que utilices.Seguimiento manual
Cuando usas este enfoque, modificas las bibliotecas que usas para recopilar información de seguimiento.
En las siguientes secciones, se muestra el caso de uso de cada instrumentación.
Instrumentación automática
El módulo @opentelemetry/sdk-trace-node proporciona instrumentación automática para las aplicaciones de Node.js.
La instrumentación automática identifica lo siguiente en tu aplicación:
- Frameworks, como Express
- Protocolos comunes, como HTTP, HTTPS y gRPC
- Bases de datos, como MySQL, MongoDB, Redis y PostgreSQL
- Otras bibliotecas dentro de tu aplicación
La instrumentación automática proporciona un registro listo para usar, de modo que no tengas que realizar cambios de código en ninguna de las bibliotecas que utilices. El código de instrumentación realiza automáticamente las siguientes acciones:
- Extrae un identificador de contexto de seguimiento de las solicitudes entrantes para permitir el seguimiento distribuido, si corresponde.
- Garantiza que el contexto de seguimiento actual se propague mientras la transacción recorre una aplicación.
- Agrega el identificador de contexto de seguimiento a las solicitudes salientes, lo que permite que el seguimiento distribuido continúe con el siguiente salto, si corresponde.
- Crea y finaliza intervalos.
El módulo usa complementos para instrumentar automáticamente tu aplicación a fin de producir intervalos y proporcionar seguimiento de extremo a extremo con solo unas pocas líneas de código.
Instrumentación manual
El módulo de seguimiento manual, @opentelemetry/sdk-trace-base, proporciona un control completo sobre la instrumentación y la creación de intervalos. No carga async_hooks
. No usa el almacenamiento local de continuación ni ningún complemento de instrumentación de forma predeterminada. El seguimiento manual tiene menos implicaciones de sobrecarga de rendimiento en comparación con el módulo de instrumentación automática.
Ejemplo
En las siguientes instrucciones, se muestra cómo usar el módulo de instrumentación automática para Compute Engine y Google Kubernetes Engine.
Compute Engine
Instala los siguientes paquetes:
npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter
Agrega el siguiente código a tu app para inicializar y registrar el exportador:
GKE
Agrega lo siguiente a la sección Dockerfile
:
RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter
Agrega el siguiente código a tu app para inicializar y registrar el exportador:
Aplicación de ejemplo mediante el uso del framework de Express
La instrumentación de OpenTelemetry Express te permite recopilar automáticamente datos de seguimiento y exportarlos al backend que elijas, lo que te permite observar los sistemas distribuidos.
Para usar OpenTelemetry en aplicaciones que usan el framework Express, completa los siguientes pasos:
Instala los siguientes paquetes:
npm install --save @opentelemetry/instrumentation-http npm install --save @opentelemetry/instrumentation-express
Agrega el siguiente código a tu app, que carga todos los complementos compatibles:
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node'); const provider = new NodeTracerProvider();
Para ver un ejemplo básico, consulta el ejemplo de OpenTelemetry Express.
Cómo crear un intervalo personalizado
Puedes agregar información adicional al seguimiento creado por el sistema si creas un intervalo personalizado.
Para crear un intervalo personalizado, agrega lo siguiente al código fuente:
getTracer
muestra una instancia del rastreador, en la quebasic
es el nombre del rastreador o la biblioteca de instrumentación. Esto indica a OpenTelemetry quién está creando intervalos.foo
es el nombre del intervalo personalizado.invoking work
es el nombre del evento de muestra. Aquí se muestra cómo usar la API deaddEvent
.
Para ver un ejemplo básico de la creación de un intervalo personalizado, consulta el ejemplo de OpenTelemetry.
Cómo configurar tu plataforma
Puedes usar Cloud Trace en Google Cloud y otras plataformas.
Ejecuta en Google Cloud
Cuando tu aplicación se ejecuta en Google Cloud, no necesitas proporcionar credenciales de autenticación en el formato de una cuenta de servicio a la biblioteca cliente. Sin embargo, debes asegurarte de que tu plataforma de Google Cloud tenga habilitado el permiso de acceso a la API de Cloud Trace.
Para obtener una lista de los entornos de Google Cloud compatibles, consulta Compatibilidad de entornos.
Para las siguientes opciones de configuración, la configuración predeterminada del permiso de acceso habilita la API de Cloud Trace:
- Entorno flexible de App Engine
Entorno estándar de App Engine
Google Kubernetes Engine (GKE)
Compute Engine
Cloud Run
Si usas permisos de acceso personalizados, debes asegurarte de que el permiso de acceso a la API de Cloud Trace esté habilitado:
Si quieres obtener información para configurar los permisos de acceso de tu entorno mediante la consola de Google Cloud, consulta Configura tu proyecto de Google Cloud.
Para los usuarios de
gcloud
, especifica los niveles de acceso con la marca--scopes
y, también, incluye el permiso de acceso a la API de Cloud Tracetrace.append
. Por ejemplo, para crear un clúster de GKE solo con la API de Cloud Trace habilitada, sigue estos pasos:gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
Ejecuta de forma local y en otros lugares
Si tu aplicación se ejecuta fuera de Google Cloud, debes proporcionar credenciales de autenticación en forma de una cuenta de servicio a la biblioteca cliente. La cuenta de servicio debe contener la función de agente de Cloud Trace. Para obtener más instrucciones, consulta Cómo crear una cuenta de servicio.
Las bibliotecas cliente de Google Cloud usan las credenciales predeterminadas de la aplicación (ADC) para encontrar las credenciales de tu aplicación.
Puedes proporcionar estas credenciales de una de estas tres maneras:
Ejecución
gcloud auth application-default login
Coloca la cuenta de servicio en una ruta predeterminada para tu sistema operativo. A continuación, se enumeran las rutas de acceso predeterminadas para Windows y Linux:
Windows:
%APPDATA%/gcloud/application_default_credentials.json
Linux:
$HOME/.config/gcloud/application_default_credentials.json
Establece la variable de entorno
GOOGLE_APPLICATION_CREDENTIALS
como la ruta a tu cuenta de servicio:
Linux/macOS
export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
Windows
set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key
PowerShell:
$env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"
Ver seguimientos
En el panel de navegación de la consola de Google Cloud, selecciona Trace y, luego, Explorador de seguimiento:
Ve al Explorador de seguimiento
Soluciona problemas
Para obtener información sobre cómo solucionar problemas con Cloud Trace, ve a la página de solución de problemas.