OpenCensus Proto Definitions

Common errors

• ModuleNotFoundError: No module named 'opencensus.proto.trace'

  cause 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.
  fix Ensure `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'

  cause 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.
  fix Double-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.

Warnings

• breaking The OpenCensus project, including this library, has been officially deprecated in favor of OpenTelemetry. New applications should use OpenTelemetry for observability.
  Fix: Consider migrating to the OpenTelemetry Python SDK (opentelemetry-sdk) and its associated proto definitions (opentelemetry-proto).
• gotcha The `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.
  Fix: If 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.
• gotcha Protobuf 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`.
  Fix: Always import specific message modules with the `_pb2` suffix, e.g., `from opencensus.proto.trace.v1 import trace_pb2`.

Install

• pip install opencensus-proto Install stable version

Imports

• trace_pb2
  wrong:

  import opencensus.proto.trace.v1.trace

  correct:

  from opencensus.proto.trace.v1 import trace_pb2

  Protobuf generated files follow a `_pb2` suffix pattern and are typically imported directly.
• metrics_pb2
  wrong:

  from opencensus.proto.metrics.v1.metrics import metrics

  correct:

  from opencensus.proto.metrics.v1 import metrics_pb2

  Access generated protobuf message classes directly from the `_pb2` module.
• agent_trace_service_pb2_grpc
  wrong:

  from opencensus.proto.agent.trace.v1 import trace_service

  correct:

  from opencensus.proto.agent.trace.v1 import trace_service_pb2_grpc

  gRPC service definitions are generated with a `_pb2_grpc` suffix.

Quickstart

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}")