Install & Compatibility
Where this runs
tested against v0.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 38.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.6s · import 0.000s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
trace_pb2
✓ from opencensus.proto.trace.v1 import trace_pb2
✗ import opencensus.proto.trace.v1.trace
Protobuf generated files follow a `_pb2` suffix pattern and are typically imported directly.
metrics_pb2
✓ from opencensus.proto.metrics.v1 import metrics_pb2
✗ from opencensus.proto.metrics.v1.metrics import metrics
Access generated protobuf message classes directly from the `_pb2` module.
agent_trace_service_pb2_grpc
✓ from opencensus.proto.agent.trace.v1 import trace_service_pb2_grpc
✗ from opencensus.proto.agent.trace.v1 import trace_service
gRPC service definitions are generated with a `_pb2_grpc` suffix.
This example demonstrates how to import a Protobuf message definition (e.g., `Span`) and instantiate it. Since `opencensus-proto` only provides definitions, usage primarily involves creating and manipulating these message objects.
import sys
from opencensus.proto.trace.v1 import trace_pb2
# Create a Span message
span = trace_pb2.Span(
trace_id=b'0123456789abcdef0123456789abcdef',
span_id=b'fedcba9876543210',
name=trace_pb2.TruncatableString(value='my_span_name'),
kind=trace_pb2.Span.SPAN_KIND_CLIENT,
start_time={'seconds': 1678886400, 'nanos': 0},
end_time={'seconds': 1678886400, 'nanos': 100000000}
)
print(f"Created Span name: {span.name.value}")
print(f"Span ID: {span.span_id.hex()}")
# To serialize to bytes
serialized_span = span.SerializeToString()
print(f"Serialized Span (first 20 bytes): {serialized_span[:20]}")
# To parse from bytes
parsed_span = trace_pb2.Span()
parsed_span.ParseFromString(serialized_span)
print(f"Parsed Span name: {parsed_span.name.value}")
Debug
Known issues
breakingThe OpenCensus project, including this library, has been officially deprecated in favor of OpenTelemetry. New applications should use OpenTelemetry for observability.fixConsider migrating to the OpenTelemetry Python SDK (opentelemetry-sdk) and its associated proto definitions (opentelemetry-proto).
affects: All versions
gotchaThe `opencensus-proto` package on PyPI (version 0.1.0) is severely outdated compared to the latest proto definitions in the GitHub repository (v0.4.x). This means the Python-generated code available via PyPI does not contain the latest OpenCensus proto features or bug fixes.fixIf you require the latest proto definitions, you would need to generate the Python code yourself from the `opencensus-proto` GitHub repository, or switch to OpenTelemetry.
affects: 0.1.0 and likely older
gotchaProtobuf messages are typically imported from generated `_pb2.py` files. Attempting to import them directly from a directory or without the `_pb2` suffix will result in a `ModuleNotFoundError` or `AttributeError`.fixAlways import specific message modules with the `_pb2` suffix, e.g., `from opencensus.proto.trace.v1 import trace_pb2`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'opencensus.proto.trace'
The `opencensus-proto` package is either not installed or the import path is incorrect. You might be missing the `v1` subdirectory or the `_pb2` suffix.
fixEnsure `pip install opencensus-proto` has been run. Verify the full import path, including the version subdirectory and `_pb2` suffix, e.g., `from opencensus.proto.trace.v1 import trace_pb2`.
AttributeError: module 'opencensus.proto.trace.v1.trace_pb2' has no attribute 'Span'
This error is unlikely for standard generated protos. However, it could occur if you're trying to access a message that doesn't exist in the imported module, or if you're trying to access it from an incorrect module. For OpenCensus, it's possible you're using an older PyPI version that doesn't contain a specific message type present in newer proto definitions.
fixDouble-check the message name (e.g., `Span` vs `span`) for case sensitivity. If the message genuinely seems missing, check the `opencensus-proto` GitHub repository for the proto definition's existence and consider the PyPI version discrepancy warning. You might be trying to use a message from a newer proto definition with an older Python package.
Upgrade
Version history
0.1.0latest on PyPI · released Apr 12, 2019
Audit
Dependencies
No dependency data recorded yet.
Resources
No resource links recorded.