Migrating from OpenCensus Python SDK and Azure Monitor OpenCensus exporter for Python to Azure Monitor OpenTelemetry Python Distro
Note
OpenCensus Python SDK is deprecated, but Microsoft supports it until retirement on September 30, 2024. We now recommend the OpenTelemetry-based Python offering and provide migration guidance.
Follow these steps to migrate Python applications to the Azure Monitor Application Insights OpenTelemetry Distro.
Warning
- The OpenCensus "How to Migrate to OpenTelemetry" blog is not applicable to Azure Monitor users.
- The OpenTelemetry OpenCensus shim is not recommended or supported by Microsoft.
- The following outlines the only migration plan for Azure Monitor customers.
Step 1: Uninstall OpenCensus libraries
Uninstall all libraries related to OpenCensus, including all Pypi packages that start with opencensus-*
.
pip freeze | grep opencensus | xargs pip uninstall -y
Step 2: Remove OpenCensus from your code
Remove all instances of the OpenCensus SDK and the Azure Monitor OpenCensus exporter from your code.
Check for import statements starting with opencensus
to find all integrations, exporters, and instances of OpenCensus API/SDK that must be removed.
The following are examples of import statements that must be removed.
from opencensus.ext.azure import metrics_exporter
from opencensus.stats import aggregation as aggregation_module
from opencensus.stats import measure as measure_module
from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer
from opencensus.ext.azure.log_exporter import AzureLogHandler
Step 3: Familiarize yourself with OpenTelemetry Python APIs/SDKs
The following documentation provides prerequisite knowledge of the OpenTelemetry Python APIs/SDKs.
- OpenTelemetry Python documentation
- Azure Monitor Distro documentation on configuration and telemetry
Note
OpenTelemetry Python and OpenCensus Python have different API surfaces, autocollection capabilities, and onboarding instructions.
Step 4: Set up the Azure Monitor OpenTelemetry Distro
Follow the getting started page to onboard onto the Azure Monitor OpenTelemetry Distro.
Changes and limitations
The following changes and limitations may be encountered when migrating from OpenCensus to OpenTelemetry.
Python < 3.7 support
OpenTelemetry's Python-based monitoring solutions only support Python 3.7 and greater, excluding the previously supported Python versions 2.7, 3.4, 3.5, and 3.6 from OpenCensus. We suggest upgrading for users who are on the older versions of Python since, as of writing this document, those versions have already reached end of life. Users who are adamant about not upgrading may still use the OpenTelemetry solutions, but may find unexpected or breaking behavior that is unsupported. In any case, the last supported version of opencensus-ext-azure always exists, and stills work for those versions, but no new releases are made for that project.
Configurations
OpenCensus Python provided some configuration options related to the collection and exporting of telemetry. You achieve the same configurations, and more, by using the OpenTelemetry Python APIs and SDK. The OpenTelemetry Azure monitor Python Distro is more of a one-stop-shop for the most common monitoring needs for your Python applications. Since the Distro encapsulates the OpenTelemetry APIs/SDk, some configuration for more uncommon use cases may not currently be supported for the Distro. Instead, you can opt to onboard onto the Azure monitor OpenTelemetry exporter, which, with the OpenTelemetry APIs/SDKs, should be able to fit your monitoring needs. Some of these configurations include:
- Custom propagators
- Custom samplers
- Adding extra span/log processors/metrics readers
Cohesion with Azure Functions
In order to provide distributed tracing capabilities for Python applications that call other Python applications within an Azure function, the package opencensus-extension-azure-functions was provided to allow for a connected distributed graph.
Currently, the OpenTelemetry solutions for Azure Monitor don't support this scenario. As a workaround, you can manually propagate the trace context in your Azure functions application as shown in the following example.
from opentelemetry.context import attach, detach
from opentelemetry.trace.propagation.tracecontext import \
TraceContextTextMapPropagator
# Context parameter is provided for the body of the function
def main(req, context):
functions_current_context = {
"traceparent": context.trace_context.Traceparent,
"tracestate": context.trace_context.Tracestate
}
parent_context = TraceContextTextMapPropagator().extract(
carrier=functions_current_context
)
token = attach(parent_context)
...
# Function logic
...
detach(token)
Extensions and exporters
The OpenCensus SDK offered ways to collect and export telemetry through OpenCensus integrations and exporters respectively. In OpenTelemetry, integrations are now referred to as instrumentations, whereas exporters have stayed with the same terminology. The OpenTelemetry Python instrumentations and exporters are a superset of what was provided in OpenCensus, so in terms of library coverage and functionality, OpenTelemetry libraries are a direct upgrade. As for the Azure Monitor OpenTelemetry Distro, it comes with some of the popular OpenTelemetry Python instrumentations out of the box so no extra code is necessary. Microsoft fully supports these instrumentations.
As for the other OpenTelemetry Python instrumentations that aren't included in this list, users may still manually instrument with them. However, it's important to note that stability and behavior aren't guaranteed or supported in those cases. Therefore, use them at your own discretion.
If you would like to suggest a community instrumentation library us to include in our distro, post or up-vote an idea in our feedback community. For exporters, the Azure Monitor OpenTelemetry distro comes bundled with the Azure Monitor OpenTelemetry exporter. If you would like to use other exporters as well, you can use them with the distro, like in this example.
TelemetryProcessors
OpenCensus Python telemetry processors are a powerful mechanism in which allowed users to modify their telemetry before they're sent to the exporter. There's no concept of TelemetryProcessors in the OpenTelemetry world, but there are APIs and classes that you can use to replicate the same behavior.
Setting Cloud Role Name and Cloud Role Instance
Follow the instructions here for how to set cloud role name and cloud role instance for your telemetry. The OpenTelemetry Azure Monitor Distro automatically fetches the values from the environment variables and fills the respective fields.
Modifying spans with SpanProcessors
Coming soon.
Modifying metrics with Views
Coming soon.
Performance Counters
The OpenCensus Python Azure Monitor exporter automatically collected system and performance related metrics called performance counters. These metrics appear in performanceCounters
in your Application Insights instance. In OpenTelemetry, we no longer send these metrics explicitly to performanceCounters
. Metrics related to incoming/outgoing requests can be found under standard metrics. If you would like OpenTelemetry to autocollect system related metrics, you can use the experimental system metrics instrumentation, contributed by the OpenTelemetry Python community. This package is experimental and not officially supported by Microsoft.
Troubleshooting
Step 1: Enable diagnostic logging
The Azure Monitor Exporter uses EventSource for its internal logging. The exporter logs are available to any EventListener by opting in to the source that's named OpenTelemetry-AzureMonitor-Exporter
. For troubleshooting steps, see OpenTelemetry Troubleshooting on GitHub.
Step 2: Test connectivity between your application host and the ingestion service
Application Insights SDKs and agents send telemetry to get ingested as REST calls at our ingestion endpoints. To test connectivity from your web server or application host computer to the ingestion service endpoints, use cURL commands or raw REST requests from PowerShell. For more information, see Troubleshoot missing application telemetry in Azure Monitor Application Insights.
Known issues
The following items are known issues for the Azure Monitor OpenTelemetry Exporters:
The operation name is missing from dependency telemetry. The missing operation name causes failures and adversely affects performance tab experience.
The device model is missing from request and dependency telemetry. The missing device model adversely affects device cohort analysis.
Support
Select a tab for the language of your choice to discover support options.
- For Azure support issues, open an Azure support ticket.
- For OpenTelemetry issues, contact the OpenTelemetry .NET community directly.
- For a list of open issues related to Azure Monitor Exporter, see the GitHub Issues Page.
OpenTelemetry feedback
To provide feedback:
- Fill out the OpenTelemetry community's customer feedback survey.
- Tell Microsoft about yourself by joining the OpenTelemetry Early Adopter Community.
- Engage with other Azure Monitor users in the Microsoft Tech Community.
- Make a feature request at the Azure Feedback Forum.