tencent cloud

Automatic Connecting Node.js Applications for K8s Environment (Recommended)
Download PDF
Last updated: 2025-03-20 19:34:07
Automatic Connecting Node.js Applications for K8s Environment (Recommended)
Last updated: 2025-03-20 19:34:07
Download PDF
For Node.js applications deployed on Kubernetes, APM offers an automatic connection scheme that enables agent auto-injection, facilitating quick application integration.
K8s environment automatically connected Node.js applications will use the community OpenTelemetry-JavaScript scheme for agent injection. For more information about OpenTelemetry-JavaScript, see the community OpenTelemetry-Javascript project.

Prerequisites

See OpenTelemetry-JavaScript scheme supported components and frameworks to ensure that the Node.js version, dependency libraries, and frameworks are within the supported range of the agent. For dependency libraries and frameworks supported by automatic Event Tracking, data reporting can be completed after a successful connection without modifying the code. If automatic Event Tracking does not meet your needs, or you need to add business layer instrumentation, use OpenTelemetry API for custom metrics.

Step 1: Install Operator.

Install Operator in the K8s cluster, it's recommended to install Operator with one click on the APM console, for details see installing tencent-opentelemetry-operator.

Step 2: Add annotation to workload.

1. Log in to TKE console.
2. Click Cluster to enter the corresponding TKE cluster.
3. In Workload, you can find the application that needs to connect APM, click More, then click Edit YAML.
4. Apply the following content in the Pod annotation, then click Complete to finish the connection.
cloud.tencent.com/inject-nodejs: "true"
cloud.tencent.com/otel-service-name: my-app  # Application name, processes that connect using the same application name are displayed in APM as multiple instances under the same application.
# The application name can be up to 63 characters and can only contain lowercase letters, digits, and the separator (-), and it must start with a lowercase letter and end with a digit or lowercase letter.
Note that this content needs to be added to spec.template.metadata.annotations, affecting the Pod's annotation, not the workload's annotation. You can see the following code snippet: 
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    k8s-app: my-app
  name: my-app
  namespace: default
spec:
  selector:
    matchLabels:
      k8s-app: my-app
  template:
    metadata:
      labels:
        k8s-app: my-app
      annotations: 
        cloud.tencent.com/inject-nodejs: "true"  # Add here
        cloud.tencent.com/otel-service-name: my-app
    spec:
      containers:
        image: my-app:0.1
        name: my-app

Notes on the Next.Js Framework

Operator uses gRPC protocol to report data by default. But if your application uses the Next.js framework, you need to change the protocol of the endpoint address to http and specify it through the environment variable OTEL_EXPORTER_OTLP_ENDPOINT. Suppose the endpoint address you get in the console is grpc://ap-shanghai.apm.tencentcs.com:4317, you need to change the endpoint address to http://ap-shanghai.apm.tencentcs.com:4317.
You can add this setting item in the project's startup script.
export OTEL_EXPORTER_OTLP_ENDPOINT=<HTTP protocol access point>
Or add environment variables through a YAML file.
env: 
- name: OTEL_EXPORTER_OTLP_ENDPOINT
  value: <HTTP protocol access point>

Connection Verification

After an annotation is added to the workload, based on different publish policies, it triggers the restart of the application Pod. The newly started Pod will automatically inject an agent and connect to the APM server to report monitoring data, with the business system reported being the default for Operator. Under normal traffic conditions, the connected application will be displayed in Application Performance Management > Application List . Click Application Name/ID to go to the application details page.
Select Instance monitoring to view the connected application instances. Since there is latency in the processing of observable data, if the application or instance does not appear in the console after connecting, please wait for about 30 seconds.

More Connection Configuration Items (Optional)

At the Workload level, you can add more annotations to adjust the connect behaviors:
Configuration Item
Description
cloud.tencent.com/apm-token
Specify the Token for the APM business system. If this configuration item is not added, the configuration of the Operator is used (corresponding to the Operator's env.APM_TOKEN field).
cloud.tencent.com/nodejs-instr-version
Specify the Node.js agent version. If this configuration item is not added, the Operator's configuration is used (corresponding to the Operator's env.NODEJS_INSTR_VERSION field). The values can be latest (default) or a specific version number. For a list of specific version numbers, see Agent Version Information. It is not recommended to fill in this field unless necessary.
loud.tencent.com/container-names
Specify the container for agent injection. This configuration item supports injecting the probe into multiple containers. Just fill in the names of multiple containers in the value of this configuration item and separate them with commas. If this configuration item is not added, the probe will be default injected into the first container. This configuration item is supported in operator 0.88 and above versions.

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback