This document contains instructions on how to set up OpenTelemetry instrumentation in your Angular applications and view your application traces in SigNoz.
Send traces to SigNoz Cloud
Based on your application environment, you can choose the setup below to send traces to SigNoz Cloud.
From VMs, there are two ways to send data to SigNoz Cloud.
- Send traces directly to SigNoz Cloud
- Send traces via OTel Collector binary (recommended)
Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Step 2. Run the application
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<service_name>"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>
<your_run_command>
ย is your run command.- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/sdk-trace-web@^1.21.0
npm install --save @opentelemetry/instrumentation@^0.48.0
npm install --save @opentelemetry/auto-instrumentations-web@^0.36.0
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.48.0
npm install --save @opentelemetry/resources@^1.21.0
npm install --save @opentelemetry/propagator-b3@^1.21.0
npm install --save @opentelemetry/semantic-conventions@^1.21.0
Step 2. Create instrument.ts
file
You need to configure the endpoint for SigNoz cloud in this file.
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
// optional - default url is http://localhost:4318/v1/traces
url: 'https://ingest.<region>.signoz.cloud:443/v1/traces', // url is optional and can be omitted
headers: {
"signoz-ingestion-key": "<your-ingestion-key>"
} // an optional object containing custom headers to be sent with each request
}),
instrumentations: [getNodeAutoInstrumentations()],
resource: resourceFromAttributes({
// highlight-next-line
[SemanticResourceAttributes.service_name]: '<service_name>'
})
});
sdk.start();
- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
Step 3. Add the below import to your main.ts
file.
import './app/instrument';
Step 4. Run the application
ng serve
The data captured with OpenTelemetry from your application should start showing on the SigNoz Traces Explorer.
Send traces via OTel Collector binary - No Code Automatic Instrumentation
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.
You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your Javascript application.
Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Step 2. Run the application
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<service_name>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>
<your_run_command>
ย is your run command.<service_name>
is name of your service
Send traces via OTel Collector binary - Code Level Automatic Instrumentation
Step 1. Install OpenTelemetry Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.
You can find instructions to install OTel Collector binary here in your VM.
While creating the config.yaml
during the installation fo the OTel Collector Binary, you need to enable CORS under the receivers section of the config file. This is needed so that you don't get CORS error which can hinder sending your Traces to SigNoz Cloud. See the code snippet below to understand how you can enable CORS in your config file:
http:
+ cors:
+ allowed_origins:
+ - <Frontend-application-URL> # URL of your Frontend application. Example -> http://localhost:4200, https://netflix.com etc.
<Frontend-application-URL>
- URL where your frontend application is running. For Example, http://localhost:4200 or https://netflix.com etc.
NOTE: Make sure to restart your collector after making the config changes
Step 2. Install OpenTelemetry packages
npm install --save @opentelemetry/sdk-trace-web@^1.21.0
npm install --save @opentelemetry/instrumentation@^0.48.0
npm install --save @opentelemetry/auto-instrumentations-web@^0.36.0
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.48.0
npm install --save @opentelemetry/resources@^1.21.0
npm install --save @opentelemetry/propagator-b3@^1.21.0
npm install --save @opentelemetry/semantic-conventions@^1.21.0
Step 3. Create instrument.ts
file
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
// optional - default url is http://localhost:4318/v1/traces
url: 'http://localhost:4318/v1/traces', // url is optional and can be omitted
}),
instrumentations: [getNodeAutoInstrumentations()],
resource: resourceFromAttributes({
// highlight-next-line
[SemanticResourceAttributes.service_name]: '<service_name>'
})
});
sdk.start();
<service_name>
is name of your service
Step 4. Add the below import to your main.ts
file.
//main.ts
import './app/instrument';
Step 5. Run the application
ng serve
You can auto-instrument sending traces from Angular application using one of the following methods:
- Using Kubernetes OTel Operator (recommended)
- Using OTel Collector Agent
K8s OTel Operator Based Automatic Instrumentation (recommended)
Send traces directly to SigNoz Cloud - Using K8s OTel Operator
For Angular application deployed on Kubernetes, you can auto-instrument the traces using Kubernetes OpenTelemetry Operator.
An OpenTelemetry Operator is a Kubernetes Operator that manages OpenTelemetry Collectors and auto-instrumentation of workloads. It basically simplifies the deployment and management of OpenTelemetry in a Kubernetes environment.
The OpenTelemetry Operator provides two Custom Resource Definitions (CRDs):
OpenTelemetryCollector
Instrumentation
The OpenTelemetryCollector
CRD allows you to deploy and manage OpenTelemetry Collectors in your Kubernetes cluster.
The Instrumentation
CRD allows you to configure and inject OpenTelemetry auto-instrumentation libraries into your workloads.
Here are the steps you need to follow to auto-instrument Angular application using OTel Operator:
Step 1. Install cert-manager
Run the following commands to apply cert manager.
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml
kubectl wait --for=condition=Available deployments/cert-manager -n cert-manager
Step 2. Install OpenTelemetry Operator
To install the operator in the existing K8s cluster, run the following command:
kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/download/v0.116.0/opentelemetry-operator.yaml
Installing the OpenTelemetry Operator sets up the necessary components and configurations to enable the observability and monitoring of applications running in the cluster.
Step 3. Setup the OpenTelemetry Collector instance
Once the opentelemetry-operator
has been deployed, you can proceed with the creation of the OpenTelemetry Collector (otelcol
) instance. The OpenTelemetry Collector collects, processes, and exports telemetry data.
There are different deployment modes for the OpenTelemetryCollector
, and you can specify them in the spec.mode section of the custom resource. The available deployment modes are:
- Daemonset
- Sidecar
- StatefulSet
- Deployment (default mode)
The default method - the Deployment
mode, will be used here.
To create a simple instance of the OpenTelemetry Collector, create a file otel-collector.yaml
with the following contents:
apiVersion: opentelemetry.io/v1alpha1
kind: OpenTelemetryCollector
metadata:
name: otel-collector
spec:
mode: deployment
config: |
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
processors:
batch: {}
resource/env:
attributes:
- key: deployment.environment
value: prod # can be dev, prod, staging etc. based on your environment
action: upsert
exporters:
debug: {}
otlp:
endpoint: "ingest.<region>.signoz.cloud:443" # replace <region> with your region of SigNoz Cloud
tls:
insecure: false
headers:
"signoz-ingestion-key": "<your-ingestion-key>" # Obtain from https://{your-signoz-tenant-url}/settings/ingestion-settings
service:
pipelines:
traces:
receivers: [otlp]
processors: [batch, resource/env]
exporters: [otlp]
- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key
Apply the above yaml file using the following command:
kubectl apply -f otel-collector.yaml
Step 4. Setup the Instrumentation instance
Once the OpenTelemetry Collector instance has been deployed, the next step will be to create an instrumentation instance, which will be responsible for sending OTLP data to the OTel Collector.
Create a file instrumentation.yaml
with the following contents:
apiVersion: opentelemetry.io/v1alpha1
kind: Instrumentation
metadata:
name: traces-instrumentation
spec:
exporter:
endpoint: https://ingest.<region>.signoz.cloud:443 # replace <region> with your region of SigNoz Cloud
env:
- name: OTEL_EXPORTER_OTLP_HEADERS
value: signoz-ingestion-key="<signoz-token>" # Obtain from https://{your-signoz-url}/settings/ingestion-settings
- name: OTEL_EXPORTER_OTLP_INSECURE
value: "false"
propagators:
- tracecontext
- baggage
- b3
sampler:
type: parentbased_traceidratio
argument: "1"
nodejs:
image: ghcr.io/open-telemetry/opentelemetry-operator/autoinstrumentation-nodejs:latest
Apply the above instrumentation using the following command:
kubectl apply -f instrumentation.yaml
Step 5. Auto-instrument your Angular app with OpenTelemetry
Create deployment.yaml
file for your Angular application as follows:
apiVersion: apps/v1
kind: Deployment
metadata:
name: angular-app
spec:
selector:
matchLabels:
app: angular-app
replicas: 1
template:
metadata:
labels:
app: angular-app
annotations:
instrumentation.opentelemetry.io/inject-nodejs: "true"
resource.opentelemetry.io/service.name: "angular-app"
spec:
containers:
- name: app
image: angular-app:latest
ports:
- containerPort: 8080
It is important to add the following annotation under spec > template > metadata > annotations
:
instrumentation.opentelemetry.io/inject-nodejs: "true"`
This helps in auto-instrumenting the traces from the Angular application.
Apply the deployment using the following command:
kubectl apply -f deployment.yaml
With this, the auto-instrumentation of traces for Angular application is ready.
Step 6. Running the Angular application
In order to run the application on port 8080, run the following commands:
export POD_NAME=$(kubectl get pod -l app=<service-name> -o jsonpath="{.items[0].metadata.name}") # service name is `angular-app` in this case.
kubectl port-forward ${POD_NAME} 8080:8080
You can now access the application on port 8080.
You can validate if your application is sending traces to SigNoz cloud here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
For Angular application deployed on Kubernetes, you need to install OTel Collector agent in your k8s infra to collect and send traces to SigNoz Cloud. You can find the instructions to install OTel Collector agent here.
Once you have set up OTel Collector agent, you can proceed with OpenTelemetry Javascript instrumentation by following either of the two:
No Code Automatic Instrumentation
Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Step 2. Run the application
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
export OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
export OTEL_SERVICE_NAME="<service_name>"
export NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>
<your_run_command>
ย is your run command.<service_name>
is name of your service
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
Code Level Automatic Instrumentation
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/sdk-trace-web@^1.21.0
npm install --save @opentelemetry/instrumentation@^0.48.0
npm install --save @opentelemetry/auto-instrumentations-web@^0.36.0
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.48.0
npm install --save @opentelemetry/resources@^1.21.0
npm install --save @opentelemetry/propagator-b3@^1.21.0
npm install --save @opentelemetry/semantic-conventions@^1.21.0
Step 2. Create instrument.ts
file
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import {
WebTracerProvider,
ConsoleSpanExporter,
SimpleSpanProcessor,
BatchSpanProcessor,
} from '@opentelemetry/sdk-trace-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { B3Propagator } from '@opentelemetry/propagator-b3';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const resource = Resource.default().merge(
new Resource({
[SemanticResourceAttributes.service_name]: '<service_name>',
[SemanticResourceAttributes.SERVICE_VERSION]: '0.1.0',
})
);
const provider = new WebTracerProvider({ resource });
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.addSpanProcessor(
new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'http://localhost:4318/v1/traces',
})
)
);
provider.register({
propagator: new B3Propagator(),
});
registerInstrumentations({
instrumentations: [
getWebAutoInstrumentations({
'@opentelemetry/instrumentation-document-load': {},
'@opentelemetry/instrumentation-user-interaction': {},
'@opentelemetry/instrumentation-fetch': {
propagateTraceHeaderCorsUrls: /.+/,
},
'@opentelemetry/instrumentation-xml-http-request': {
propagateTraceHeaderCorsUrls: /.+/,
},
}),
],
});
<service_name>
: Name of your service.
Step 3. Add the below import to your main.ts
file.
import './app/instrument';
Step 4. Run the application
ng serve
From Windows, there are two ways to send data to SigNoz Cloud.
- Send traces directly to SigNoz Cloud
- Send traces via OTel Collector binary (recommended)
Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Step 2. Run the application
$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT="ingest.<region>.signoz.cloud:443"
$env:OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
$env:OTEL_SERVICE_NAME="<service_name>"
$env:OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
$env:NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>
<your_run_command>
ย is your run command.- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
Send traces directly to SigNoz Cloud - Code Level Automatic Instrumentation
Step 1. Install OpenTelemetry packages
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
// optional - default url is http://localhost:4318/v1/traces
url: 'https://ingest.<region>.signoz.cloud:443/v1/traces', // url is optional and can be omitted
headers: {
"signoz-ingestion-key": "<your-ingestion-key>"
} // an optional object containing custom headers to be sent with each request
}),
instrumentations: [getNodeAutoInstrumentations()],
resource: resourceFromAttributes({
// highlight-next-line
[SemanticResourceAttributes.service_name]: '<service_name>'
})
});
sdk.start();
- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
Step 3. Add the below import to your main.ts
file.
import './app/instrument';
Step 4. Run the application
ng serve
The data captured with OpenTelemetry from your application should start showing on the SigNoz Traces Explorer.
Send traces via OTel Collector binary - No Code Automatic Instrumentation
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.
You can find instructions to install OTel Collector binary here in your VM. Once you are done setting up your OTel Collector binary, you can follow the below steps for instrumenting your Javascript application.
Send traces directly to SigNoz Cloud - No Code Automatic Instrumentation (recommended)
Step 1. Install OpenTelemetry packages
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
Step 2. Run the application
$env:OTEL_TRACES_EXPORTER="otlp"
$env:OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
$env:OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
$env:OTEL_SERVICE_NAME="<service_name>"
$env:NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
<your_run_command>
<your_run_command>
ย is your run command.<service_name>
is name of your service
Send traces via OTel Collector binary - Code Level Automatic Instrumentation
Step 1. Install OpenTelemetry Collector binary
OTel Collector binary helps to collect logs, hostmetrics, resource and infra attributes. It is recommended to install Otel Collector binary to collect and send traces to SigNoz cloud. You can correlate signals and have rich contextual data through this way.
You can find instructions to install OTel Collector binary here in your VM.
While creating the config.yaml
during the installation fo the OTel Collector Binary, you need to enable CORS under the receivers section of the config file. This is needed so that you don't get CORS error which can hinder sending your Traces to SigNoz Cloud. See the code snippet below to understand how you can enable CORS in your config file:
http:
+ cors:
+ allowed_origins:
+ - <Frontend-application-URL> # URL of your Frontend application. Example -> http://localhost:4200, https://netflix.com etc.
<Frontend-application-URL>
- URL where your frontend application is running. For Example, http://localhost:4200 or https://netflix.com etc.
NOTE: Make sure to restart your collector after making the config changes
Step 2. Install OpenTelemetry packages
npm install --save @opentelemetry/sdk-trace-web@^1.21.0
npm install --save @opentelemetry/instrumentation@^0.48.0
npm install --save @opentelemetry/auto-instrumentations-web@^0.36.0
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.48.0
npm install --save @opentelemetry/resources@^1.21.0
npm install --save @opentelemetry/propagator-b3@^1.21.0
npm install --save @opentelemetry/semantic-conventions@^1.21.0
Step 3. Create instrument.ts
file
import * as opentelemetry from '@opentelemetry/sdk-node';
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
import { resourceFromAttributes } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const sdk = new opentelemetry.NodeSDK({
traceExporter: new OTLPTraceExporter({
// optional - default url is http://localhost:4318/v1/traces
url: 'http://localhost:4318/v1/traces', // url is optional and can be omitted
}),
instrumentations: [getNodeAutoInstrumentations()],
resource: resourceFromAttributes({
// highlight-next-line
[SemanticResourceAttributes.service_name]: '<service_name>'
})
});
sdk.start();
<service_name>
is name of your service
Step 4. Add the below import to your main.ts
file.
import './app/instrument';
Step 5. Run the application
ng serve
There are two ways to send data to SigNoz Cloud. You can containerize the images in both the cases.
Send traces directly to SigNoz Cloud
Step 1. Configure OpenTelemetry to run in Docker Container
Add the following in your Dockerfile.
...
# Install opentelemetry dependencies
RUN npm install @opentelemetry/api@1.9.0 @opentelemetry/auto-instrumentations-node@0.57.0
...
# Set environment variables for OpenTelemetry
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
ENV OTEL_SERVICE_NAME="<service_name>"
ENV OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your-ingestion-key>"
ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
...
- Set the
<region>
to match your SigNoz Cloud region - Replace
<your-ingestion-key>
with your SigNoz ingestion key <service_name>
is name of your service
The above steps install OpenTelemetry dependencies directly inside the Docker container without altering package.json
of project & sets environment variables to export the traces.
Step 2. Run your Docker container
Here's how you can run your docker container:
docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>
Replace
<image-name>
,<host-port>
, and<container-port>
with values for your application.-d
runs the container in detached mode-p
maps a host port to a container port
Step 3. Validate if your application is sending traces to SigNoz cloud by following the instructions here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
Send traces via OTel Collector binary
Step 1. Configure OpenTelemetry to run in Docker Container
Add the following in your Dockerfile.
# get the OpenTelemetry Collector //STAGE 1
FROM otel/opentelemetry-collector-contrib:0.131.0 AS otel
...
# Install OpenTelemetry Node.js dependencies
RUN npm install @opentelemetry/api@1.9.0 @opentelemetry/auto-instrumentations-node@0.57.0
# Copy OpenTelemetry Collector binary + config from STAGE 1
COPY --from=otel /otelcol-contrib /otelcol-contrib
COPY --from=otel /etc/otelcol-contrib /etc/otelcol-contrib
COPY config.yaml /etc/otelcol-contrib/config.yaml
...
# Expose ports for app + collector
EXPOSE 4317 4318 <APP_PORT>
...
# Environment variables for Node.js instrumentation
ENV NODE_OPTIONS="--require @opentelemetry/auto-instrumentations-node/register"
ENV OTEL_SERVICE_NAME="node-js-auto-instrument"
ENV OTEL_TRACES_EXPORTER="otlp"
ENV OTEL_NODE_RESOURCE_DETECTORS="env,host,os"
# Point Node.js exporter to local collector
ENV OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4317"
ENV OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
...
# Run both Collector and Node.js app in same container
CMD sh -c "/otelcol-contrib --config=/etc/otelcol-contrib/config.yaml & <run_command>"
Make sure you have config.yaml
in root
of the application. This config.yaml should be copied from third step of this
- Replace
<run_command>
with the command to run your application <service_name>
is name of your service
Step 2. Run your Docker container
Run your docker container to start exporting.
docker build -t <image-name> . && docker run -d -p <host-port>:<container-port> <image-name>
Replace
<image-name>
,<host-port>
, and<container-port>
with values for your application.-d
runs the container in detached mode-p
maps a host port to a container port
Step 3. You can validate if your application is sending traces to SigNoz cloud by following the instructions here.
In case you encounter an issue where all applications do not get listed in the services section then please refer to the troubleshooting section.
Send Traces to SigNoz Self-Host
Instrumenting your Angular App with OpenTelemetry ๐
Pre-requisites
Enable CORS in the OTel Receiver. Add the below required changes in the otel-collector-config.yaml
file which can be generally found here.
http:
+ cors:
+ allowed_origins:
+ - https://netflix.com # URL of your Frontend application
Make sure to restart the container after making the config changes
Step 1. Install OpenTelemetry packages.
npm install --save @opentelemetry/sdk-trace-web@^1.21.0
npm install --save @opentelemetry/instrumentation@^0.48.0
npm install --save @opentelemetry/auto-instrumentations-web@^0.36.0
npm install --save @opentelemetry/exporter-trace-otlp-http@^0.48.0
npm install --save @opentelemetry/resources@^1.21.0
npm install --save @opentelemetry/propagator-b3@^1.21.0
npm install --save @opentelemetry/semantic-conventions@^1.21.0
Step 2. Create instrument.ts
file
You need to configure the endpoint for SigNoz Self-Host in this file.
import { registerInstrumentations } from '@opentelemetry/instrumentation';
import {
WebTracerProvider,
ConsoleSpanExporter,
SimpleSpanProcessor,
BatchSpanProcessor,
} from '@opentelemetry/sdk-trace-web';
import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { Resource } from '@opentelemetry/resources';
import { B3Propagator } from '@opentelemetry/propagator-b3';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const resource = Resource.default().merge(
new Resource({
[SemanticResourceAttributes.service_name]: '<service_name>',
[SemanticResourceAttributes.SERVICE_VERSION]: '0.1.0',
})
);
const provider = new WebTracerProvider({ resource });
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
provider.addSpanProcessor(
new BatchSpanProcessor(
new OTLPTraceExporter({
url: 'http://127.0.0.1:4318/v1/traces', //url of OpenTelemetry Collector',
})
)
);
provider.register({
propagator: new B3Propagator(),
});
registerInstrumentations({
instrumentations: [
getWebAutoInstrumentations({
'@opentelemetry/instrumentation-document-load': {},
'@opentelemetry/instrumentation-user-interaction': {},
'@opentelemetry/instrumentation-fetch': {
propagateTraceHeaderCorsUrls: /.+/,
},
'@opentelemetry/instrumentation-xml-http-request': {
propagateTraceHeaderCorsUrls: /.+/,
},
}),
],
});
Again, http://localhost:4318/v1/traces
is the default url for sending your tracing data. We are assuming you have installed SigNoz on your localhost. Based on your environment, you can update it accordingly. It should be in the following format:
http://<IP of SigNoz backend>:4318/v1/traces
NOTE: Remember to allow incoming requests to port 4318 of machine where SigNoz backend is hosted.
Sample Angular App
- Sample Angular App - contains
instrument.ts
file with placeholder for URL and Ingestion Details (For SigNoz Cloud)
Best Practices for Configuring OpenTelemetry in Production Angular Environments
When deploying Angular applications instrumented with OpenTelemetry to production, it's crucial to optimize for performance, reliability, and security. Here are some best practices to consider:
- Implement Proper Sampling
- Use intelligent sampling to reduce data volume without losing important information.
- Consider using a parent-based sampler to maintain consistency across traces.
Example configuration:
import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/core';
const sampler = new ParentBasedSampler({
root: new TraceIdRatioBasedSampler(0.1), // Sample 10% of traces
});
const provider = new WebTracerProvider({
sampler,
// other config...
});
- Use Batch Processing
- Implement batch processing to reduce network overhead and improve performance.
Example:
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
const exporter = new OTLPTraceExporter({
url: 'https://your-collector-endpoint',
});
const provider = new WebTracerProvider();
provider.addSpanProcessor(new BatchSpanProcessor(exporter, {
maxQueueSize: 100,
maxExportBatchSize: 10,
scheduledDelayMillis: 500,
}));
- Secure Your Data
- Use HTTPS for all communication with your collector.
- Implement proper authentication for your collector endpoints.
- Be cautious about what data you include in spans, avoiding sensitive information.
- Optimize Performance
- Use async operations where possible to avoid blocking the main thread.
- Implement custom spans judiciously, focusing on critical paths and operations.
Example of an optimized custom span:
import { trace } from '@opentelemetry/api';
async function performCriticalOperation() {
const span = trace.getTracer('critical-ops').startSpan('criticalOperation');
try {
// Perform operation
const result = await someAsyncOperation();
span.setAttributes({ 'operation.result': result });
return result;
} catch (error) {
span.recordException(error);
throw error;
} finally {
span.end();
}
}
- Implement Proper Error Handling
- Ensure all exceptions are properly caught and recorded in spans.
- Use span events to record important application events.
- Use Resource Detection
- Implement resource detection to automatically capture environment information.
Example:
import { Resource } from '@opentelemetry/resources';
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
const resource = Resource.default().merge(
new Resource({
[SemanticResourceAttributes.service_name]: 'my-angular-app',
[SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
environment: 'production',
})
);
const provider = new WebTracerProvider({
resource: resource,
// other config...
});
- Monitor Your Monitoring
- Implement health checks for your OpenTelemetry pipeline.
- Set up alerts for issues with data collection or exporting.
Troubleshooting
When implementing OpenTelemetry in Angular applications, you may encounter several challenges. Here are some common issues and their solutions:
- Context Propagation Issues
Challenge: Traces not connecting properly across different services or components.
Solution:
- Ensure that the
W3CTraceContextPropagator
is properly configured in yourapp.module.ts
. - Use the
@opentelemetry/context-zone
package to manage context in Angular's Zone.js.
Example configuration:
import { W3CTraceContextPropagator } from '@opentelemetry/core';
import { ZoneContextManager } from '@opentelemetry/context-zone';
// In your OpenTelemetry configuration
const provider = new WebTracerProvider({
// ... other config
});
provider.register({
propagator: new W3CTraceContextPropagator(),
contextManager: new ZoneContextManager()
});
- Performance Overhead
Challenge: Noticeable performance degradation after implementing OpenTelemetry.
Solution:
- Use sampling to reduce the volume of telemetry data.
- Optimize your instrumentation by focusing on critical paths.
Example of configuring a sampler:
import { ParentBasedSampler, TraceIdRatioBasedSampler } from '@opentelemetry/core';
const sampler = new ParentBasedSampler({
root: new TraceIdRatioBasedSampler(0.5), // Sample 50% of traces
});
const provider = new WebTracerProvider({
sampler,
// ... other config
});
- Asynchronous Operations Not Being Traced
Challenge: Traces not capturing asynchronous operations correctly.
Solution:
- Ensure that Zone.js is properly integrated with OpenTelemetry.
- Manually create spans for complex asynchronous operations.
Example of manually creating a span:
import { trace } from '@opentelemetry/api';
async function complexOperation() {
const span = trace.getTracer('my-tracer').startSpan('complexOperation');
try {
// Perform async operation
await someAsyncTask();
span.end();
} catch (error) {
span.recordException(error);
span.end();
throw error;
}
}
- Incorrect Configuration of Exporters
Challenge: Telemetry data not reaching the backend (e.g., SigNoz).
Solution:
- Double-check the exporter configuration, especially the endpoint URLs.
- Ensure that CORS is properly configured if your collector is on a different domain.
Example of configuring the OTLPTraceExporter:
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
const exporter = new OTLPTraceExporter({
url: 'http://your-collector-url:4318/v1/traces', // Adjust this URL
});
const provider = new WebTracerProvider();
provider.addSpanProcessor(new BatchSpanProcessor(exporter));
- Handling Third-Party Libraries
Challenge: Difficulty in tracing operations within third-party libraries.
Solution:
- Use auto-instrumentation packages when available.
- For libraries without auto-instrumentation, wrap their methods with custom spans.
Example of wrapping a third-party library method:
import { trace } from '@opentelemetry/api';
function wrapThirdPartyMethod(originalMethod) {
return function(...args) {
const span = trace.getTracer('my-tracer').startSpan('thirdPartyOperation');
try {
const result = originalMethod.apply(this, args);
span.end();
return result;
} catch (error) {
span.recordException(error);
span.end();
throw error;
}
}
}
// Usage
thirdPartyLibrary.someMethod = wrapThirdPartyMethod(thirdPartyLibrary.someMethod);
By being aware of these common challenges and their solutions, you can more effectively implement and troubleshoot OpenTelemetry in your Angular applications.