# Campman Observability Library
A Python library for OpenTelemetry observability setup with Google Cloud Platform integration, specifically designed for Flask applications.
## Features
- **Flask and Requests Instrumentation**: Automatic tracing for Flask applications and HTTP requests
- **GCP Cloud Trace Integration**: Seamless integration with Google Cloud Trace
- **Trace Context Propagation**: Handles trace context from HTTP requests, Pub/Sub messages, and environment variables
- **Robust Error Handling**: Graceful fallbacks to ensure your application continues running even if tracing fails
- **Utility Functions**: Convenient functions for span management and trace context handling
## Installation
### From Private GitHub Repository
```bash
# Install latest version
pip install git+ssh://git@github.com/ingka-group-digital/campman-observability-lib-py.git
# Install specific version
pip install git+ssh://git@github.com/ingka-group-digital/campman-observability-lib-py.git@v0.1.0
```
For detailed installation instructions, see [INSTALLATION.md](INSTALLATION.md).
## Quick Start
```python
from flask import Flask
from campman_observability import setup_tracing, setup_trace_context
app = Flask(__name__)
# Setup tracing for your Flask app
tracer = setup_tracing(
app=app,
service_name="my-service",
service_namespace="my-namespace"
)
@app.route("/")
def main():
# Setup trace context in request handlers
setup_trace_context(
project_id="your-gcp-project-id",
global_log_fields={}
)
return "Hello, World!"
@app.route("/trigger-via-pubsub", methods=["POST"])
def trigger_via_pubsub():
setup_trace_context(
project_id="your-gcp-project-id",
global_log_fields={}
)
return "Handled Pub/Sub trigger"
if __name__ == "__main__":
app.run()
```
## API Reference
### `setup_tracing(app, service_name, service_namespace)`
Set up OpenTelemetry tracing for a Flask application.
**Parameters:**
- `app` (Flask): Flask application instance
- `service_name` (str): Name of the service for tracing
- `service_namespace` (str): Namespace for the service
**Returns:**
- `Tracer`: Configured tracer instance, or `None` if setup fails
**Raises:**
- `ValueError`: If required parameters are missing or invalid
### `setup_trace_context(project_id, global_log_fields)`
Set up trace context from various sources (HTTP headers, Pub/Sub messages, environment variables).
**Parameters:**
- `project_id` (str): GCP project ID for trace formatting
- `global_log_fields` (dict): Dictionary to update with trace fields
**Raises:**
- `ValueError`: If `project_id` is not provided or `global_log_fields` is not a dictionary
### `get_trace_id()`
Get the current trace ID for logging purposes.
**Returns:**
- `str`: The current trace ID, or `None` if not available
### `add_span_attributes(**attributes)`
Add custom attributes to the current span.
**Parameters:**
- `**attributes`: Key-value pairs to add as span attributes
### `create_child_span(name, **attributes)`
Create a child span with the given name and attributes.
**Parameters:**
- `name` (str): Name of the span
- `**attributes`: Additional attributes to set on the span
**Returns:**
- `Span`: The created span or `None` if creation fails
## Trace Context Sources
The library automatically detects and uses trace context from multiple sources:
1. **Pub/Sub Messages**: Extracts trace context from message attributes
2. **HTTP Headers**: Reads `X-Cloud-Trace-Context` header
3. **Environment Variables**: Falls back to `TRACE_CONTEXT` environment variable
4. **Current Context**: Uses the current OpenTelemetry context as final fallback
## GCP Cloud Trace Format
The library uses Google Cloud Trace format for trace context:
`TRACE_ID/SPAN_ID;o=SAMPLED_FLAG`
Where:
- `TRACE_ID`: 32-character hexadecimal string
- `SPAN_ID`: Numeric span identifier
- `SAMPLED_FLAG`: `1` for sampled, `0` for not sampled
## Error Handling
The library is designed with robust error handling:
- Configuration errors (missing required parameters) raise `ValueError`
- Runtime tracing failures are logged but don't break application flow
- Graceful fallbacks ensure your application continues running
## Development
### Setting up development environment
```bash
git clone https://github.com/ingka-group-digital/campman-observability-lib-py.git
cd campman-observability-lib-py
pip install -e .[dev]
```
### Running tests
```bash
pytest
```
### Code formatting
```bash
black .
flake8 .
mypy .
```
## Requirements
- Python 3.8+
- Flask 3.1.1+
- OpenTelemetry packages (see requirements.txt)
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request
## Support
For issues and questions, please use the [GitHub issue tracker](https://github.com/ingka-group-digital/campman-observability-lib-py/issues).
Raw data
{
"_id": null,
"home_page": null,
"name": "campman-observability-lib-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "opentelemetry, observability, tracing, flask, gcp, google-cloud",
"author": null,
"author_email": "Francesco Deleo <francesco.deleo@ingka.com>",
"download_url": "https://files.pythonhosted.org/packages/2a/77/060648104da8572fbd5335e0f2aca121085a27655421ca7b9059e83a6efc/campman_observability_lib_py-0.1.2.tar.gz",
"platform": null,
"description": "# Campman Observability Library\n\nA Python library for OpenTelemetry observability setup with Google Cloud Platform integration, specifically designed for Flask applications.\n\n## Features\n\n- **Flask and Requests Instrumentation**: Automatic tracing for Flask applications and HTTP requests\n- **GCP Cloud Trace Integration**: Seamless integration with Google Cloud Trace\n- **Trace Context Propagation**: Handles trace context from HTTP requests, Pub/Sub messages, and environment variables\n- **Robust Error Handling**: Graceful fallbacks to ensure your application continues running even if tracing fails\n- **Utility Functions**: Convenient functions for span management and trace context handling\n\n## Installation\n\n### From Private GitHub Repository\n\n```bash\n# Install latest version\npip install git+ssh://git@github.com/ingka-group-digital/campman-observability-lib-py.git\n\n# Install specific version\npip install git+ssh://git@github.com/ingka-group-digital/campman-observability-lib-py.git@v0.1.0\n```\n\nFor detailed installation instructions, see [INSTALLATION.md](INSTALLATION.md).\n\n## Quick Start\n\n```python\nfrom flask import Flask\nfrom campman_observability import setup_tracing, setup_trace_context\n\napp = Flask(__name__)\n\n# Setup tracing for your Flask app\ntracer = setup_tracing(\n app=app,\n service_name=\"my-service\",\n service_namespace=\"my-namespace\"\n)\n\n@app.route(\"/\")\ndef main():\n # Setup trace context in request handlers\n setup_trace_context(\n project_id=\"your-gcp-project-id\",\n global_log_fields={}\n )\n return \"Hello, World!\"\n\n@app.route(\"/trigger-via-pubsub\", methods=[\"POST\"])\ndef trigger_via_pubsub():\n setup_trace_context(\n project_id=\"your-gcp-project-id\",\n global_log_fields={}\n )\n return \"Handled Pub/Sub trigger\"\n\nif __name__ == \"__main__\":\n app.run()\n```\n\n## API Reference\n\n### `setup_tracing(app, service_name, service_namespace)`\n\nSet up OpenTelemetry tracing for a Flask application.\n\n**Parameters:**\n\n- `app` (Flask): Flask application instance\n- `service_name` (str): Name of the service for tracing\n- `service_namespace` (str): Namespace for the service\n\n**Returns:**\n\n- `Tracer`: Configured tracer instance, or `None` if setup fails\n\n**Raises:**\n\n- `ValueError`: If required parameters are missing or invalid\n\n### `setup_trace_context(project_id, global_log_fields)`\n\nSet up trace context from various sources (HTTP headers, Pub/Sub messages, environment variables).\n\n**Parameters:**\n\n- `project_id` (str): GCP project ID for trace formatting\n- `global_log_fields` (dict): Dictionary to update with trace fields\n\n**Raises:**\n\n- `ValueError`: If `project_id` is not provided or `global_log_fields` is not a dictionary\n\n### `get_trace_id()`\n\nGet the current trace ID for logging purposes.\n\n**Returns:**\n\n- `str`: The current trace ID, or `None` if not available\n\n### `add_span_attributes(**attributes)`\n\nAdd custom attributes to the current span.\n\n**Parameters:**\n\n- `**attributes`: Key-value pairs to add as span attributes\n\n### `create_child_span(name, **attributes)`\n\nCreate a child span with the given name and attributes.\n\n**Parameters:**\n\n- `name` (str): Name of the span\n- `**attributes`: Additional attributes to set on the span\n\n**Returns:**\n\n- `Span`: The created span or `None` if creation fails\n\n## Trace Context Sources\n\nThe library automatically detects and uses trace context from multiple sources:\n\n1. **Pub/Sub Messages**: Extracts trace context from message attributes\n2. **HTTP Headers**: Reads `X-Cloud-Trace-Context` header\n3. **Environment Variables**: Falls back to `TRACE_CONTEXT` environment variable\n4. **Current Context**: Uses the current OpenTelemetry context as final fallback\n\n## GCP Cloud Trace Format\n\nThe library uses Google Cloud Trace format for trace context:\n`TRACE_ID/SPAN_ID;o=SAMPLED_FLAG`\n\nWhere:\n\n- `TRACE_ID`: 32-character hexadecimal string\n- `SPAN_ID`: Numeric span identifier\n- `SAMPLED_FLAG`: `1` for sampled, `0` for not sampled\n\n## Error Handling\n\nThe library is designed with robust error handling:\n\n- Configuration errors (missing required parameters) raise `ValueError`\n- Runtime tracing failures are logged but don't break application flow\n- Graceful fallbacks ensure your application continues running\n\n## Development\n\n### Setting up development environment\n\n```bash\ngit clone https://github.com/ingka-group-digital/campman-observability-lib-py.git\ncd campman-observability-lib-py\npip install -e .[dev]\n```\n\n### Running tests\n\n```bash\npytest\n```\n\n### Code formatting\n\n```bash\nblack .\nflake8 .\nmypy .\n```\n\n## Requirements\n\n- Python 3.8+\n- Flask 3.1.1+\n- OpenTelemetry packages (see requirements.txt)\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for your changes\n5. Run the test suite\n6. Submit a pull request\n\n## Support\n\nFor issues and questions, please use the [GitHub issue tracker](https://github.com/ingka-group-digital/campman-observability-lib-py/issues).\n",
"bugtrack_url": null,
"license": null,
"summary": "OpenTelemetry observability library for Flask applications with Google Cloud Platform integration",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/ingka-group-digital/campman-observability-lib-py",
"Issues": "https://github.com/ingka-group-digital/campman-observability-lib-py/issues",
"Repository": "https://github.com/ingka-group-digital/campman-observability-lib-py"
},
"split_keywords": [
"opentelemetry",
" observability",
" tracing",
" flask",
" gcp",
" google-cloud"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f05e393c0b81101f4778c303fde073008a80e9d1537e5272fa41f9d4cf2a0dba",
"md5": "45bd69a0ff1b74fb6501bfcb9c7d12c7",
"sha256": "ce7f19dff30344f16fc0fb7441d6e8f97ea2843b10483339597653f117f4c779"
},
"downloads": -1,
"filename": "campman_observability_lib_py-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "45bd69a0ff1b74fb6501bfcb9c7d12c7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8867,
"upload_time": "2025-08-04T14:51:38",
"upload_time_iso_8601": "2025-08-04T14:51:38.973726Z",
"url": "https://files.pythonhosted.org/packages/f0/5e/393c0b81101f4778c303fde073008a80e9d1537e5272fa41f9d4cf2a0dba/campman_observability_lib_py-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2a77060648104da8572fbd5335e0f2aca121085a27655421ca7b9059e83a6efc",
"md5": "9352d66fd5b8b9f4f5cc7a4fd2b9b382",
"sha256": "61e53be53fe0b11ddface76a09e7a8d5e661d2fb9866f47e36efccc8d6f93b68"
},
"downloads": -1,
"filename": "campman_observability_lib_py-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "9352d66fd5b8b9f4f5cc7a4fd2b9b382",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 12569,
"upload_time": "2025-08-04T14:51:39",
"upload_time_iso_8601": "2025-08-04T14:51:39.849592Z",
"url": "https://files.pythonhosted.org/packages/2a/77/060648104da8572fbd5335e0f2aca121085a27655421ca7b9059e83a6efc/campman_observability_lib_py-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-04 14:51:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ingka-group-digital",
"github_project": "campman-observability-lib-py",
"github_not_found": true,
"lcname": "campman-observability-lib-py"
}
JSON
