cisco-opentelemetry-node
v1.13.6
Published
Epsagon Instrumentation for Node.js
Downloads
25
Readme
otel-js
This package provides OpenTelemetry-compliant tracing to Javascript applications for the collection of distributed tracing and performance metrics in Cisco Telescope.
Contents
- otel-js
Installation
Install packages
To install Cisco OpenTelemetry Distribution simply run:
npm install cisco-opentelemetry-node
Library initialization
Cisco OpenTelemetry Distribution is activated and instruments the supported libraries once the module is imported.
javascript
const { ciscoTracing } = require('cisco-opentelemetry-node');
const userOptions = {
serviceName: 'my-app-name',
ciscoToken: 'cisco-token',
};
await ciscoTracing.init(userOptions);
typescript
import { ciscoTracing, Options } from 'cisco-opentelemetry-node';
const userOptions: Partial<Options> = {
serviceName: 'my-app-name',
ciscoToken: 'sometoken',
};
await ciscoTracing.init(userOptions);
OpenTelemetry Collector Configuration
By default, Cisco OpenTelemetry Distribution exports data directly to Cisco Telescope's infrastructure backend. Existing OpenTelemetery Collector is supported, the following configuration can be applied
Configure custom trace exporter
Cisco OpenTelemetry Distribution supports configure multiple custom exporters. Example for create OtlpGrpc Span exporter to local OpenTelemetry collector including metadata(headers) injection:
const { ciscoTracing } = require('cisco-opentelemetry-node');
const userOptions = {
serviceName: 'my-app-name',
ciscoToken: 'cisco-token',
exporters: [
{
type: 'otlp-grpc',
collectorEndpoint: 'grpc://localhost:4317',
customHeaders: {
'someheader-to-inject': 'header value',
},
},
],
};
await ciscoTracing.init(userOptions);
Configure custom OpenTelemetry collector to export trace data to Cisco Telescope's external collector.
collector.yaml ...
exporters:
otlphttp:
traces_endpoint: https://production.cisco-udp.com/trace-collector:80
headers:
authorization: <Your Telescope Token>
compression: gzip
service:
pipelines:
traces:
exporters: [otlphttp]
Existing OpenTelemetry Instrumentation
Notice: Only relevant if interested in streaming existing OpenTelemetry workloads. Cisco Telescope. supports native OpenTelemetery traces.
const traceProvider = new NodeTracerProvider({
resource: Resource(),
});
const collectorOptions = {
url: 'https://production.cisco-udp.com/trace-collector:80',
headers: {
authorization: '<Your Telescope Token>',
},
};
const httpExporter = new HTTPTraceExporter(collectorOptions);
traceProvider.addSpanProcessor(new BatchSpanProcessor(httpExporter));
Supported Runtimes
| Platform Version | Supported |
| ---------------- | --------- |
| Node.JS v14
| ✅ |
| Node.JS v12
| ✅ |
| Node.JS v10
| ✅ |
Frameworks
Cisco OpenTelemetry JS Distribution is extending Native OpenTelemetry, supported frameworks available here.
Supported Libraries
Cisco OpenTelemetry JS Distribution is extending Native OpenTelemetry, supported libraries available here.
Cisco OpenTelemetry JS Distribution provides out-of-the-box instrumentation (tracing) and advanced payload collections for many popular frameworks and libraries.
| Library | Extended Support Version | | ------- | ------------------------ | | http | Fully supported | | aws-sdk | V2, V3 | | amqplib | ^0.5.5 | | grpc-js | ^1.X | | redis | ^2.6.0, ^3.0.0 |
Configuration
Advanced options can be configured as a parameter to the init() method:
| Parameter | Env | Type | Default | Description |
| --------------- | ---------------------- | ------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ciscoToken | CISCO_TOKEN | string | - | Cisco account token |
| serviceName | OTEL_SERVICE_NAME | string | application
| Application name that will be set for traces |
| debug | CISCO_DEBUG | string | false
| Debug logs |
| payloadsEnabled | CISCO_PAYLOADS_ENABLED | boolean | false
| Whether the span should include paylaods or not according to this list. |
Exporter options
| Parameter | Env | Type | Default | Description |
| ----------------- | ----------------------- | ------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| collectorEndpoint | OTEL_COLLECTOR_ENDPOINT | string | https://production.cisco-udp.com/trace-collector:80
| The address of the trace collector to send traces to |
| type | OTEL_EXPORTER_TYPE | string | otlp-http
| The exporter type to use (Currently only otlp-http
are supported). Multiple exporter option available via init function see example below |
| customHeaders | None | Map<string, string> | {} | Extra headers to inject to the exporter (in gRPC to the metadata, in http to Headers) |
Getting Help
If you have any issue around using the library or the product, please don't hesitate to:
- Use the documentation.
- Use the help widget inside the product.
- Open an issue in GitHub.
Opening Issues
If you encounter a bug with the Cisco OpenTelemetry Distribution for JavaScript, we want to hear about it.
When opening a new issue, please provide as much information about the environment:
- Library version, JavaScript runtime version, dependencies, etc.
- Snippet of the usage.
- A reproducible example can really help.
The GitHub issues are intended for bug reports and feature requests. For help and questions about Cisco Telescope, use the help widget inside the product.
License
Provided under the Apache 2.0. See LICENSE for details.
Copyright 2022, Cisco