otel-java

Note: This repository is archived since Telescope is no longer supported

This package provides OpenTelemetry-compliant tracing to Java applications for the collection of distributed tracing and performance metrics in Cisco Telescope.

Contents

• Installation
  • Download The Javaagent
  • Library initialization
  • OpenTelemetry Collector Configuration
  • Existing OpenTelemetry Instrumentation
• Supported Runtimes
• Configuration
• Getting Help
• Opening Issues
• License

Installation

Download the javaagent

Download the latest version

Library initialization

Cisco OpenTelemetry Distribution is activated and instruments the supported libraries once the app has started with the javaagent

To initialize the library, you'll need a cisco-token, which is taken from your Account tab on the Telescope console Settings page.

• On Linux, run:

export OTEL_SERVICE_NAME=APP
export CISCO_TOKEN=<token>

java -javaagent:./cisco-otel-javaagent.jar \
  -jar <myapp>.jar

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 the configuration of multiple custom exporters. Note that you will need to handle your exporter authorization. Example for creating OtlpGrpc Span exporter to local OpenTelemetry collector including metadata(headers) injection:

export OTEL_TRACES_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=none
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4317

export OTEL_SERVICE_NAME=APP
export CISCO_TOKEN=<token>

java -javaagent:./cisco-telescope-javaagent.jar \
  -jar <myapp>.jar

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
    headers:
      authorization: Bearer <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.

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_METRICS_EXPORTER=none
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://production.cisco-udp.com/trace-collector
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer <Your Telescope Token>"

java -javaagent:./opentelemetry_javaagent.jar \
  -jar <myapp>.jar

Supported Runtimes

The agent works with Java runtimes version 8 and higher.

Configuration

Cisco OTel Agent support all existing Open Telemetry configurations and provides new defaults for some of them.

In addition, Cisco OTel agent exports another set of Properties/Variables for the specific Cisco Agent configuration

Cisco OTel Agent configurations:

System property	Environment variable	Default	Description
cisco.token	CISCO_TOKEN	None	Cisco account token, should be taken from your Account tab on the Telescope console Settings page.
otel.service.name	OTEL_SERVICE_NAME	application	Java service name
cisco.payloads_enabled	CISCO_PAYLOADS_ENABLED	False	Whether to capture additional payloads and experimental attributes. Follow Specifications for more information.
cisco.debug	-	False	Enable debug prints for troubleshooting

Open Telemetry defaults:

System property	Environment variable	Default	Description
OTEL_METRICS_EXPORTER	otel.metrics.exporter	None	By default, metrics are currently not supported
OTEL_INSTRUMENTATION_RUNTIME-METRICS_ENABLED	otel.instrumentation.runtime-metrics.enabled	None	By default, metrics are currently not supported
OTEL_TRACES_EXPORTER	otel.traces.exporter	otlp-http	Otlp over HTTP exporter
OTEL_EXPORTER_OTLP_ENDPOINT	otel.exporter.otlp.endpoint	https://production.cisco-udp.com/trace-collector	The Cisco Otlp-gRPC collector URL path

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