scout-apm-logging 0.1.2__tar.gz

scout_apm_logging-0.1.2/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.1
+Name: scout-apm-logging
+Version: 0.1.2
+Summary: Scout APM Python Logging Agent
+Author: Quinn Milionis
+Author-email: quinn@scoutapm.com
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: opentelemetry-api (>=1.26.0,<2.0.0)
+Requires-Dist: opentelemetry-exporter-otlp (>=1.26.0,<2.0.0)
+Requires-Dist: opentelemetry-sdk (>=1.26.0,<2.0.0)
+Requires-Dist: scout-apm (>=3.1.0,<4.0.0)
+Description-Content-Type: text/markdown
+
+# Scout APM Python Logging Agent
+
+A Python package for detailed, easy-to-navigate, managed log monitoring. Sign up for an account at https://www.scoutapm.com to start monitoring your logs and application performance in minutes.
+
+This is to be used alongside [scout-apm-python](https://github.com/scoutapp/scout_apm_python) package, thusly requires it. 
+
+To use Scout, you'll need to
+[sign up for an account](https://scoutapm.com/users/sign_up) or use
+[our Heroku Addon](https://devcenter.heroku.com/articles/scout).
+
+Then, you'll need to enable logging for your individual apps, which will provide a `SCOUT_LOGS_INGEST_KEY`
+
+## Installation
+
+Install the Scout APM Python Logging Agent using pip:
+
+```
+pip install scout-apm-python-logging
+```
+
+## Setup and Usage
+
+### Using dictConfig
+
+We recommend setting up the `OtelScoutHandler` using Python's [`dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig). Here's an example configuration:
+
+```python
+import logging
+from logging.config import dictConfig
+from scout_apm_python_logging import OtelScoutHandler
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        },
+    },
+    "handlers": {
+        "otel": {
+            "level": "DEBUG",
+            "class": "scout_apm_python_logging.OtelScoutHandler",
+            "service_name": "your-service-name",
+        },
+        "console": {
+            "level": "DEBUG",
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+        },
+    },
+    "loggers": {
+        "": {  # Root logger
+            "handlers": ["console", "otel"],
+            "level": "DEBUG",
+        },
+    },
+}
+
+# Apply the logging configuration
+dictConfig(LOGGING_CONFIG)
+```
+
+### Adding to an Existing Logger
+
+You can also add the `OtelScoutHandler` to an existing logger:
+
+```python
+import logging
+from scout_apm_python_logging import OtelScoutHandler
+
+# Get your logger
+logger = logging.getLogger(__name__)
+
+# Create and add the OtelScoutHandler
+handler = OtelScoutHandler(service_name="your-service-name")
+logger.addHandler(handler)
+```
+
+## Configuration
+
+The `OtelScoutHandler` only requires `service_name` to be supplied to the handler as an argument:
+
+If the `scout-apm` is [configured](https://scoutapm.com/docs/python#some-configuration-required) (You've set your `SCOUT_KEY`, etc), you'll only need add your `SCOUT_LOGS_INGEST_KEY` to whichever configuration you are already using. This can also be set as an environment variable.
+
+Make sure to set the `SCOUT_LOGS_INGEST_KEY` variable before running your application.
+
+## OpenTelemetry
+
+The Scout APM Python Logging Agent leverages [OpenTelemetry Python](https://github.com/open-telemetry/opentelemetry-python) to provide powerful and standardized logging capabilities. OpenTelemetry is an observability framework for cloud-native software, offering a collection of tools, APIs, and SDKs for generating, collecting, and exporting telemetry data (metrics, logs, and traces).
+
+Our `OtelScoutHandler` utilizes the OpenTelemetry Python SDK to:
+
+1. Create a `LoggerProvider` with a custom resource that includes your service name and instance ID.
+2. Set up an OTLP (OpenTelemetry Protocol) exporter configured to send logs to Scout's ingestion endpoint.
+3. Add a `BatchLogRecordProcessor` to efficiently process and export log records.
+4. Integrate with Scout APM's request tracking to enrich logs with request-specific information.
+
+This integration allows you to benefit from OpenTelemetry's standardized approach to observability while leveraging Scout APM's powerful analysis and visualization tools.
+
+For more information about OpenTelemetry and its Python SDK, visit the [OpenTelemetry Python documentation](https://opentelemetry.io/docs/instrumentation/python/).
+
+## Additional Resources
+
+For more information on using Scout APM and advanced configuration options, please refer to our [documentation](https://docs.scoutapm.com).
+
+## Support
+
+If you encounter any issues or have questions, please [open an issue](https://github.com/scoutapp/scout-apm-python-logging/issues) on our GitHub repository or contact our support team at support@scoutapm.com.

scout_apm_logging-0.1.2/README.md

@@ -0,0 +1,109 @@
+# Scout APM Python Logging Agent
+
+A Python package for detailed, easy-to-navigate, managed log monitoring. Sign up for an account at https://www.scoutapm.com to start monitoring your logs and application performance in minutes.
+
+This is to be used alongside [scout-apm-python](https://github.com/scoutapp/scout_apm_python) package, thusly requires it. 
+
+To use Scout, you'll need to
+[sign up for an account](https://scoutapm.com/users/sign_up) or use
+[our Heroku Addon](https://devcenter.heroku.com/articles/scout).
+
+Then, you'll need to enable logging for your individual apps, which will provide a `SCOUT_LOGS_INGEST_KEY`
+
+## Installation
+
+Install the Scout APM Python Logging Agent using pip:
+
+```
+pip install scout-apm-python-logging
+```
+
+## Setup and Usage
+
+### Using dictConfig
+
+We recommend setting up the `OtelScoutHandler` using Python's [`dictConfig`](https://docs.python.org/3/library/logging.config.html#logging.config.dictConfig). Here's an example configuration:
+
+```python
+import logging
+from logging.config import dictConfig
+from scout_apm_python_logging import OtelScoutHandler
+
+LOGGING_CONFIG = {
+    "version": 1,
+    "disable_existing_loggers": False,
+    "formatters": {
+        "standard": {
+            "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+        },
+    },
+    "handlers": {
+        "otel": {
+            "level": "DEBUG",
+            "class": "scout_apm_python_logging.OtelScoutHandler",
+            "service_name": "your-service-name",
+        },
+        "console": {
+            "level": "DEBUG",
+            "class": "logging.StreamHandler",
+            "formatter": "standard",
+        },
+    },
+    "loggers": {
+        "": {  # Root logger
+            "handlers": ["console", "otel"],
+            "level": "DEBUG",
+        },
+    },
+}
+
+# Apply the logging configuration
+dictConfig(LOGGING_CONFIG)
+```
+
+### Adding to an Existing Logger
+
+You can also add the `OtelScoutHandler` to an existing logger:
+
+```python
+import logging
+from scout_apm_python_logging import OtelScoutHandler
+
+# Get your logger
+logger = logging.getLogger(__name__)
+
+# Create and add the OtelScoutHandler
+handler = OtelScoutHandler(service_name="your-service-name")
+logger.addHandler(handler)
+```
+
+## Configuration
+
+The `OtelScoutHandler` only requires `service_name` to be supplied to the handler as an argument:
+
+If the `scout-apm` is [configured](https://scoutapm.com/docs/python#some-configuration-required) (You've set your `SCOUT_KEY`, etc), you'll only need add your `SCOUT_LOGS_INGEST_KEY` to whichever configuration you are already using. This can also be set as an environment variable.
+
+Make sure to set the `SCOUT_LOGS_INGEST_KEY` variable before running your application.
+
+## OpenTelemetry
+
+The Scout APM Python Logging Agent leverages [OpenTelemetry Python](https://github.com/open-telemetry/opentelemetry-python) to provide powerful and standardized logging capabilities. OpenTelemetry is an observability framework for cloud-native software, offering a collection of tools, APIs, and SDKs for generating, collecting, and exporting telemetry data (metrics, logs, and traces).
+
+Our `OtelScoutHandler` utilizes the OpenTelemetry Python SDK to:
+
+1. Create a `LoggerProvider` with a custom resource that includes your service name and instance ID.
+2. Set up an OTLP (OpenTelemetry Protocol) exporter configured to send logs to Scout's ingestion endpoint.
+3. Add a `BatchLogRecordProcessor` to efficiently process and export log records.
+4. Integrate with Scout APM's request tracking to enrich logs with request-specific information.
+
+This integration allows you to benefit from OpenTelemetry's standardized approach to observability while leveraging Scout APM's powerful analysis and visualization tools.
+
+For more information about OpenTelemetry and its Python SDK, visit the [OpenTelemetry Python documentation](https://opentelemetry.io/docs/instrumentation/python/).
+
+## Additional Resources
+
+For more information on using Scout APM and advanced configuration options, please refer to our [documentation](https://docs.scoutapm.com).
+
+## Support
+
+If you encounter any issues or have questions, please [open an issue](https://github.com/scoutapp/scout-apm-python-logging/issues) on our GitHub repository or contact our support team at support@scoutapm.com.

scout_apm_logging-0.1.2/pyproject.toml

@@ -0,0 +1,38 @@
+[tool.poetry]
+name = "scout-apm-logging"
+version = "0.1.2"
+description = "Scout APM Python Logging Agent"
+authors = ["Quinn Milionis <quinn@scoutapm.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.9"
+opentelemetry-api = "^1.26.0"
+opentelemetry-sdk = "^1.26.0"
+opentelemetry-exporter-otlp = "^1.26.0"
+scout-apm = "^3.1.0"
+
+
+[tool.poetry.group.dev.dependencies]
+taskipy = "^1.13.0"
+pytest = "^8.3.2"
+coverage = "^7.6.1"
+black = "^24.8.0"
+pytest-cov = "^5.0.0"
+flake8 = "^7.1.1"
+flake8-black = "^0.3.6"
+mypy = "^1.11.1"
+flask = "^3.0.3"
+
+[tool.taskipy.tasks]
+test = "pytest . --cov-report=term-missing --cov=."
+lint = "task flake8 && task mypy"
+flake8 = "flake8 ."
+black = "black ."
+mypy = "poetry run mypy . --install-types --non-interactive --ignore-missing-imports"
+format = "task black"
+check = "task format && task lint && task test"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

scout_apm_logging-0.1.2/scout_apm_logging/__init__.py

@@ -0,0 +1 @@
+from scout_apm_logging.handler import OtelScoutHandler

scout_apm_logging-0.1.2/scout_apm_logging/handler.py

@@ -0,0 +1,122 @@
+import logging
+import os
+import threading
+from opentelemetry import _logs
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from scout_apm.core.tracked_request import TrackedRequest
+from scout_apm.core import scout_config
+from scout_apm_logging.utils.operation_utils import get_operation_detail
+
+
+class OtelScoutHandler(logging.Handler):
+    def __init__(self, service_name):
+        super().__init__()
+        self.logger_provider = None
+        self.service_name = self._get_service_name(service_name)
+        self.ingest_key = self._get_ingest_key()
+        self.endpoint = self._get_endpoint()
+        self.setup_logging()
+        self._handling_log = threading.local()
+
+    def setup_logging(self):
+        self.logger_provider = LoggerProvider(
+            resource=Resource.create(
+                {
+                    "service.name": self.service_name,
+                    "service.instance.id": os.uname().nodename,
+                }
+            )
+        )
+        _logs.set_logger_provider(self.logger_provider)
+
+        otlp_exporter = OTLPLogExporter(
+            headers={"x-telemetryhub-key": self.ingest_key},
+            endpoint=self.endpoint,
+        )
+        self.logger_provider.add_log_record_processor(
+            BatchLogRecordProcessor(otlp_exporter)
+        )
+
+        self.otel_handler = LoggingHandler(
+            level=logging.NOTSET, logger_provider=self.logger_provider
+        )
+
+    def emit(self, record):
+        if getattr(self._handling_log, "value", False):
+            # We're already handling a log message, don't try to get the TrackedRequest
+            return self.otel_handler.emit(record)
+
+        try:
+            self._handling_log.value = True
+            scout_request = TrackedRequest.instance()
+
+            if scout_request:
+                operation_detail = get_operation_detail(scout_request)
+                if operation_detail:
+                    setattr(
+                        record,
+                        operation_detail.entrypoint_attribute,
+                        operation_detail.name,
+                    )
+
+                # Add Scout-specific attributes to the log record
+                record.scout_request_id = scout_request.request_id
+                record.scout_start_time = scout_request.start_time.isoformat()
+                if scout_request.end_time:
+                    record.scout_end_time = scout_request.end_time.isoformat()
+
+                # Add duration if the request is completed
+                if scout_request.end_time:
+                    record.scout_duration = (
+                        scout_request.end_time - scout_request.start_time
+                    ).total_seconds()
+
+                setattr(record, "service.name", self.service_name)
+
+                # Add tags
+                for key, value in scout_request.tags.items():
+                    setattr(record, f"scout_tag_{key}", value)
+
+                # Add the current span's operation if available
+                current_span = scout_request.current_span()
+                if current_span:
+                    record.scout_current_operation = current_span.operation
+
+            self.otel_handler.emit(record)
+        except Exception as e:
+            print(f"Error in OtelScoutHandler.emit: {e}")
+        finally:
+            self._handling_log.value = False
+
+    def close(self):
+        if self.logger_provider:
+            self.logger_provider.shutdown()
+        super().close()
+
+    # These getters will be replaced by a config module to read these values
+    # from a config file or environment variables as the Scout APM agent does.
+
+    def _get_service_name(self, provided_name):
+        if provided_name:
+            return provided_name
+
+        # Try to get the name from Scout APM config
+        scout_name = scout_config.value("name")
+        if scout_name:
+            return scout_name
+
+        return "unnamed-service"
+
+    def _get_endpoint(self):
+        return (
+            scout_config.value("logs_reporting_endpoint") or "otlp.scoutotel.com:4317"
+        )
+
+    def _get_ingest_key(self):
+        ingest_key = scout_config.value("logs_ingest_key")
+        if not ingest_key:
+            raise ValueError("SCOUT_LOGS_INGEST_KEY is not set")
+        return ingest_key

scout_apm_logging-0.1.2/scout_apm_logging/otel_logger.py

@@ -0,0 +1,48 @@
+import logging
+
+from opentelemetry._logs import set_logger_provider
+from opentelemetry.exporter.otlp.proto.grpc._log_exporter import OTLPLogExporter
+from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+
+
+class OTELLoggingManager:
+    def __init__(self, service_name):
+        self.service_name = service_name
+        self.logger_provider = None
+        self.logs_reporting_endpoint = "https://otlp.scoutotel.com:4317"
+
+        # placeholder, we will want to get this from a config or env var.
+        self.ingest_key = "aaaa-bbbb-cccc-dddd"
+
+    def setup_logging(self):
+        self.logger_provider = LoggerProvider(
+            resource=Resource.create({"service.name": self.service_name})
+        )
+        set_logger_provider(self.logger_provider)
+
+        otlp_exporter = OTLPLogExporter(
+            headers={"x-telemetryhub-key": self.ingest_key},
+            endpoint=self.logs_reporting_endpoint,
+        )
+
+        self.logger_provider.add_log_record_processor(
+            BatchLogRecordProcessor(otlp_exporter)
+        )
+
+        handler = LoggingHandler(
+            level=logging.NOTSET, logger_provider=self.logger_provider
+        )
+        # add otel logging handler to root logger
+        logging.getLogger().addHandler(handler)
+
+    def shutdown(self):
+        if self.logger_provider:
+            self.logger_provider.shutdown()
+
+
+def initialize_otel_logging(service_name):
+    manager = OTELLoggingManager(service_name)
+    manager.setup_logging()
+    return manager

scout_apm_logging-0.1.2/scout_apm_logging/utils/__init__.py

@@ -0,0 +1 @@
+from .operation_utils import get_operation_detail

scout_apm_logging-0.1.2/scout_apm_logging/utils/operation_utils.py

@@ -0,0 +1,48 @@
+from typing import Optional
+from dataclasses import dataclass
+from scout_apm.core.tracked_request import TrackedRequest
+
+
+@dataclass
+class OperationDetail:
+    name: str
+    type: str
+
+    @property
+    def entrypoint_attribute(self) -> str:
+        return f"{self.type}_entrypoint"
+
+
+class OperationType:
+    CONTROLLER = "controller"
+    JOB = "job"
+    CUSTOM = "custom"
+
+
+OPERATION_PREFIXES = {
+    "Controller/": OperationType.CONTROLLER,
+    "Job/": OperationType.JOB,
+    "Custom/": OperationType.CUSTOM,
+}
+
+
+def get_operation_detail(record: TrackedRequest) -> Optional[OperationDetail]:
+    def extract_operation(operation: str) -> Optional[OperationDetail]:
+        for prefix, op_type in OPERATION_PREFIXES.items():
+            if operation.startswith(prefix):
+                return OperationDetail(name=operation[len(prefix) :], type=op_type)
+        return None
+
+    # Check the operation attribute first
+    operation = getattr(record, "operation", None)
+    if operation:
+        return extract_operation(operation)
+
+    # Fall back to checking spans
+    spans = getattr(record, "complete_spans", None) or []
+    for span in reversed(spans):
+        result = extract_operation(span.operation)
+        if result:
+            return result
+
+    return None