Skip to main content

Cisco Distribution for OpenTelemetry

Project description

otel-py

PIP Published Version Apache License Coverage

Trace

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

Contents

Installation

Requirements

Python >=3.8, <4.0 pip3 >= 22.0

Install packages

To install Cisco OpenTelemetry Distribution simply run:

pip install cisco-telescope

Full instrumentation support

To install the required dependencies for all relevant supported instrumentation frameworks run:

telescope-bootstrap

Library initialization

Cisco OpenTelemetry Distribution is activated and instruments the supported libraries once the tracing.init() has returned.

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

from cisco_telescope import tracing

tracing.init(
  service_name="<your-service-name>",
  cisco_token="<your-cisco-token>"
)

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:

from cisco_telescope import tracing, options

tracing.init(
  service_name="<your-service-name>",
  exporters=[
    options.ExporterOptions(
      exporter_type="otlp-grpc",
      collector_endpoint="grpc://localhost:4317"
    ),
  ]
)

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.

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
    OTLPSpanExporter as OTLPHTTPExporter,
)

provider = TracerProvider(resource=Resource.create())
trace.set_tracer_provider(provider)

http_exporter = OTLPHTTPExporter(
  endpoint="https://production.cisco-udp.com/trace-collector",
  headers= {
    "authorization": "Bearer <Your Telescope Token>",
  },
)

processor = BatchSpanProcessor(http_exporter)
provider.add_span_processor(processor)

Supported Runtimes

Cisco OpenTelemetry Distribution supports Python 3.6+

Supported Libraries

Cisco OpenTelemetry Python Distribution is extending Native OpenTelemetry, supported libraries available here.

Cisco OpenTelemetry Python Distribution provides out-of-the-box instrumentation (tracing) and advanced payload collections for many popular frameworks and libraries.

Library Extended Support Version
requests Fully supported
aiohttp Fully supported
grpc Client/Server Unary support

Configuration

Advanced options can be configured as a parameter to the init() method:

Parameter Env Type Default Description
cisco_token CISCO_TOKEN string - Cisco account token
service_name OTEL_SERVICE_NAME string application Application name that will be set for traces
debug CISCO_DEBUG string False Debug logs
payloads_enabled CISCO_PAYLOADS_ENABLED string True Debug logs

Exporter options

Parameter Env Type Default Description
collector_endpoint OTEL_COLLECTOR_ENDPOINT string https://production.cisco-udp.com/trace-collector 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 is supported). Multiple exporter option available via init function see example below

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.

License

Provided under the Apache 2.0. See LICENSE for details.

Copyright 2022, Cisco

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cisco-telescope-1.7.0.tar.gz (20.9 kB view details)

Uploaded Source

Built Distribution

cisco_telescope-1.7.0-py3-none-any.whl (27.7 kB view details)

Uploaded Python 3

File details

Details for the file cisco-telescope-1.7.0.tar.gz.

File metadata

  • Download URL: cisco-telescope-1.7.0.tar.gz
  • Upload date:
  • Size: 20.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.3 readme-renderer/35.0 requests/2.28.1 requests-toolbelt/0.9.1 urllib3/1.26.11 tqdm/4.64.0 importlib-metadata/4.12.0 keyring/23.7.0 rfc3986/2.0.0 colorama/0.4.5 CPython/3.9.13

File hashes

Hashes for cisco-telescope-1.7.0.tar.gz
Algorithm Hash digest
SHA256 126316cbb32506ce3fff9f8cc740f4648285b1a07375de87e1ced32fce71fae7
MD5 0ee0d0b4f5b9698672c2ef0c9db291d3
BLAKE2b-256 8a2dbec55354cdefec7763d66951f58abac42509c8bac10e09617d39a87406e6

See more details on using hashes here.

File details

Details for the file cisco_telescope-1.7.0-py3-none-any.whl.

File metadata

  • Download URL: cisco_telescope-1.7.0-py3-none-any.whl
  • Upload date:
  • Size: 27.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.3 readme-renderer/35.0 requests/2.28.1 requests-toolbelt/0.9.1 urllib3/1.26.11 tqdm/4.64.0 importlib-metadata/4.12.0 keyring/23.7.0 rfc3986/2.0.0 colorama/0.4.5 CPython/3.9.13

File hashes

Hashes for cisco_telescope-1.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 ee250ea29e413563b4071bd89a7016061f2ab163d4d958f7d2f192e015b19e74
MD5 0e1f240b6ea98cc7b2ca67b1bbb09946
BLAKE2b-256 cd902b0b2a7f347bf8c5540a77f1f96bbcbbc54d53ef984e019726a2c53219ed

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page