croudtech-python-gcp-otel 1.0.1

OpenTelemetry configuration utilities for GCP Cloud Trace and Cloud Logging

CroudTech Python GCP OpenTelemetry

OpenTelemetry configuration utilities for GCP Cloud Trace and Cloud Logging integration.

Installation

# Install from PyPI
pip install croudtech-python-gcp-otel

# Install from GitHub
pip install git+https://github.com/CroudTech/croudtech-python-gcp-otel.git

# Install a specific version
pip install git+https://github.com/CroudTech/croudtech-python-gcp-otel.git@v1.0.0

# Install with Poetry
poetry add croudtech-python-gcp-otel

# Or from GitHub with Poetry
poetry add git+https://github.com/CroudTech/croudtech-python-gcp-otel.git

All instrumentations (Django, requests, psycopg2, logging) are included by default.

Usage

Basic Setup

from croudtech_gcp_otel import configure_telemetry

# Configure using environment variables
configure_telemetry()

Configuration via Environment Variables

• GCP_PROJECT_ID or GOOGLE_CLOUD_PROJECT - GCP project ID for Cloud Trace
• GCP_REGION - GCP region (default: europe-west2)
• SERVICE_NAME - Service name for tracing
• SERVICE_VERSION - Service version
• K_SERVICE - Cloud Run service name (auto-detected)
• K_REVISION - Cloud Run revision (auto-detected)

Explicit Configuration

from croudtech_gcp_otel import configure_telemetry, TelemetryConfig

config = TelemetryConfig(
    service_name="my-service",
    service_namespace="my-namespace",
    project_id="my-gcp-project",
    region="europe-west2",
    service_version="1.0.0",
    # Instrumentation flags (all default to True)
    instrument_django=True,
    instrument_requests=True,
    instrument_psycopg2=True,
    instrument_logging=True,
    # Psycopg2 SQL commenter options
    psycopg2_enable_commenter=True,
    psycopg2_commenter_options={
        "db_driver": True,
        "dbapi_threadsafety": True,
        "dbapi_level": True,
        "libpq_version": True,
        "driver_paramstyle": True,
    },
)
configure_telemetry(config)

TelemetryConfig Options

Option	Type	Default	Description
service_name	str	K_SERVICE or SERVICE_NAME env var	Service name for tracing
service_version	str	K_REVISION or SERVICE_VERSION env var	Service version
service_namespace	str	""	Service namespace for grouping
project_id	str	GCP_PROJECT_ID or GOOGLE_CLOUD_PROJECT env var	GCP project ID
region	str	GCP_REGION env var or europe-west2	GCP region
instrument_django	bool	True	Enable Django auto-instrumentation
instrument_requests	bool	True	Enable requests library instrumentation
instrument_psycopg2	bool	True	Enable PostgreSQL instrumentation
instrument_logging	bool	True	Enable logging instrumentation
psycopg2_enable_commenter	bool	True	Add SQL comments with trace info
psycopg2_commenter_options	dict	See above	Configure SQL commenter fields

JSON Logging for GCP Cloud Logging

from croudtech_gcp_otel import configure_logging
import logging

# Configure root logger with JSON formatting
configure_logging()

# Or with custom log level
configure_logging(level=logging.DEBUG)

# Or with explicit project ID for trace correlation
configure_logging(gcp_project_id="my-gcp-project")

Or use the formatter directly:

import logging
from croudtech_gcp_otel import JSONFormatter

handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter(
    gcp_project_id="my-gcp-project",  # For trace correlation URLs
    include_extra_fields=True,         # Include custom log record fields
))
logging.getLogger().addHandler(handler)

The JSON output includes:

• timestamp, severity, message, logger, module, function, line
• exception with type, message, and stacktrace (when applicable)
• logging.googleapis.com/trace, logging.googleapis.com/spanId, logging.googleapis.com/trace_sampled for Cloud Trace correlation

Manual Span Creation

from croudtech_gcp_otel import get_tracer, create_span_with_attributes

tracer = get_tracer(__name__)

with create_span_with_attributes(tracer, "my_operation", {"custom.attr": "value"}):
    # your code here
    pass

GCP Resource Attributes

Get resource attributes for custom OpenTelemetry configurations:

from croudtech_gcp_otel import get_gcp_resource_attributes, TelemetryConfig

# Using defaults from environment
attributes = get_gcp_resource_attributes()

# Or with explicit config
config = TelemetryConfig(service_name="my-service", project_id="my-project")
attributes = get_gcp_resource_attributes(config)

# Returns dict with: service.name, service.version, cloud.provider, cloud.platform,
# cloud.region, cloud.account.id, gcp.project_id, gcp.region, and Cloud Run
# specific attributes when running on Cloud Run

Features

• GCP Cloud Trace Integration: Automatic export of traces to Cloud Trace
• W3C Trace Context Propagation: Standard distributed tracing headers
• GCP Cloud Trace Propagation: Native GCP trace header support
• Auto-instrumentation: Django, requests, psycopg2, and logging
• JSON Logging: GCP Cloud Logging compatible structured logs with trace correlation
• App Hub Topology: Resource attributes for service topology visualization