graftcode-telemetry-appinsights 1.0.0__py3-none-any.whl

graftcode_telemetry_appinsights/GraftCodeAppInsightsConnector.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import Callable, Union
+
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnectorOptions import GraftCodeAppInsightsConnectorOptions
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnectorPipeline import GraftCodeAppInsightsConnectorPipeline
+
+ConfigureCallback = Callable[[GraftCodeAppInsightsConnectorOptions], None]
+
+
+class GraftCodeAppInsightsConnector:
+
+    @staticmethod
+    def start(
+            service_name_or_configure: Union[str, ConfigureCallback, GraftCodeAppInsightsConnectorOptions, None],
+    ) -> GraftCodeAppInsightsConnectorPipeline:
+        if service_name_or_configure is None:
+            raise ValueError("start requires a service name, a configure callback or options")
+
+        if isinstance(service_name_or_configure, GraftCodeAppInsightsConnectorOptions):
+            return GraftCodeAppInsightsConnectorPipeline(service_name_or_configure)
+
+        options = GraftCodeAppInsightsConnectorOptions()
+        if callable(service_name_or_configure):
+            service_name_or_configure(options)
+        else:
+            options.service_name = service_name_or_configure
+
+        return GraftCodeAppInsightsConnectorPipeline(options)

graftcode_telemetry_appinsights/GraftCodeAppInsightsConnectorOptions.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import os
+from typing import Callable, Optional, Union
+
+from hypertube.utils.logging.LogsLevel import LogsLevel
+
+
+class GraftCodeAppInsightsConnectorOptions:
+    CONNECTION_STRING_VARIABLE = "APPLICATIONINSIGHTS_CONNECTION_STRING"
+
+    def __init__(
+            self,
+            service_name: str = "",
+            connection_string: Optional[str] = None,
+            minimum_log_level: LogsLevel = LogsLevel.Info,
+            traces_per_second: Optional[float] = None,
+            enable_console_logging: bool = True,
+    ) -> None:
+        self.service_name = service_name
+        self.connection_string = connection_string
+        self.minimum_log_level = minimum_log_level
+        self.traces_per_second = traces_per_second
+        self.enable_console_logging = enable_console_logging
+        self._environment: Callable[[str], Optional[str]] = os.environ.get
+
+    def resolve_connection_string(self) -> Optional[str]:
+        if not GraftCodeAppInsightsConnectorOptions._is_blank(self.connection_string):
+            return self.connection_string
+
+        environment_value = self._environment(GraftCodeAppInsightsConnectorOptions.CONNECTION_STRING_VARIABLE)
+        return None if GraftCodeAppInsightsConnectorOptions._is_blank(environment_value) else environment_value
+
+    def validate(self) -> None:
+        if GraftCodeAppInsightsConnectorOptions._is_blank(self.service_name):
+            raise ValueError("service_name must be configured for Azure Monitor telemetry.")
+
+        if self.minimum_log_level is None:
+            raise ValueError("minimum_log_level must not be None.")
+
+        if self.traces_per_second is not None and not self.traces_per_second > 0:
+            raise ValueError("traces_per_second must be greater than zero.")
+
+    @staticmethod
+    def _is_blank(value: Union[str, None]) -> bool:
+        return value is None or not str(value).strip()

graftcode_telemetry_appinsights/GraftCodeAppInsightsConnectorPipeline.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import atexit
+import logging
+import sys
+import threading
+import traceback
+from types import TracebackType
+from typing import Optional, Tuple, Type
+
+from opentelemetry import context as otel_context
+from opentelemetry._logs import LogRecord, SeverityNumber
+from opentelemetry.sdk._logs import LoggerProvider
+from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.sdk.trace.sampling import ALWAYS_ON
+from opentelemetry.trace import Context, SpanKind
+
+from hypertube.utils.logging.LogsLevel import LogsLevel
+
+from graftcode_instrumentation import GraftcodeInstrumentation
+
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnectorOptions import GraftCodeAppInsightsConnectorOptions
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsLogger import GraftCodeAppInsightsLogger
+from graftcode_telemetry_appinsights.RateLimitedSampler import RateLimitedSampler
+
+_DEFAULT_FLUSH_MILLISECONDS = 5000
+
+_MISSING_CONNECTION_STRING = (
+    "Application Insights telemetry for {ServiceName} is disabled: no connection string was configured. "
+    "Set " + GraftCodeAppInsightsConnectorOptions.CONNECTION_STRING_VARIABLE + " in this process or set "
+    "GraftCodeAppInsightsConnectorOptions.connection_string.")
+
+_PYTHON_LEVELS = {
+    LogsLevel.Trace: 5,
+    LogsLevel.Debug: logging.DEBUG,
+    LogsLevel.Info: logging.INFO,
+    LogsLevel.Warning: logging.WARNING,
+    LogsLevel.Error: logging.ERROR,
+    LogsLevel.Off: logging.CRITICAL + 1,
+}
+
+_STANDARD_RECORD_ATTRIBUTES = frozenset(
+    logging.LogRecord("", 0, "", 0, "", None, None).__dict__.keys()) | {"message", "asctime", "taskName"}
+
+
+class _HypertubeLogHandler(logging.Handler):
+
+    def __init__(self, logger_provider: LoggerProvider) -> None:
+        super().__init__(level=0)
+        self._logger = logger_provider.get_logger(GraftcodeInstrumentation.LOGGER_NAME)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            attributes = {
+                key: value for key, value in record.__dict__.items()
+                if key not in _STANDARD_RECORD_ATTRIBUTES and isinstance(value, (str, bool, int, float))
+            }
+
+            if record.exc_info and record.exc_info[1] is not None:
+                exception = record.exc_info[1]
+                attributes["exception.type"] = type(exception).__qualname__
+                if str(exception):
+                    attributes["exception.message"] = str(exception)
+                attributes["exception.stacktrace"] = "".join(traceback.format_exception(*record.exc_info))
+
+            self._logger.emit(LogRecord(
+                timestamp=int(record.created * 1e9),
+                context=otel_context.get_current(),
+                severity_number=_HypertubeLogHandler._severity(record.levelno),
+                severity_text="Information" if record.levelno == logging.INFO else record.levelname.capitalize(),
+                body=record.getMessage(),
+                attributes=attributes))
+        except Exception:
+            self.handleError(record)
+
+    @staticmethod
+    def _severity(level: int) -> SeverityNumber:
+        if level >= logging.ERROR:
+            return SeverityNumber.ERROR
+        if level >= logging.WARNING:
+            return SeverityNumber.WARN
+        if level >= logging.INFO:
+            return SeverityNumber.INFO
+        if level >= logging.DEBUG:
+            return SeverityNumber.DEBUG
+        return SeverityNumber.TRACE
+
+
+class GraftCodeAppInsightsConnectorPipeline:
+
+    def __init__(
+            self,
+            options: GraftCodeAppInsightsConnectorOptions,
+            providers: Optional[Tuple[TracerProvider, LoggerProvider]] = None,
+    ) -> None:
+        options.validate()
+
+        self._flush_gate = threading.Lock()
+        self._closed = False
+        self.service_name = options.service_name
+        connection_string = options.resolve_connection_string() if providers is None else None
+        self._exporting_to_app_insights = connection_string is not None
+
+        if providers is not None:
+            self.tracer_provider, self.logger_provider = providers
+        elif connection_string is not None:
+            self.tracer_provider, self.logger_provider = GraftCodeAppInsightsConnectorPipeline._build_exporting_sdk(
+                self.service_name, connection_string, options.traces_per_second)
+        else:
+            self.tracer_provider, self.logger_provider = GraftCodeAppInsightsConnectorPipeline._build_local_sdk(
+                self.service_name)
+
+        self.tracer = self.tracer_provider.get_tracer(self.service_name)
+        self.logger = GraftCodeAppInsightsLogger(
+            self.service_name,
+            self.logger_provider.get_logger(self.service_name),
+            options.minimum_log_level,
+            True if options.enable_console_logging else None)
+
+        self._hypertube_logger = logging.getLogger(GraftcodeInstrumentation.LOGGER_NAME)
+        self._hypertube_logger.setLevel(_PYTHON_LEVELS[options.minimum_log_level])
+        self._hypertube_logger.propagate = False
+        self._log_handler = _HypertubeLogHandler(self.logger_provider)
+        self._hypertube_logger.addHandler(self._log_handler)
+        self.instrumentation = GraftcodeInstrumentation.attach(self.tracer_provider, self._hypertube_logger)
+
+        if providers is None and connection_string is None:
+            self._warn_about_missing_connection_string(options)
+
+        atexit.register(self.close)
+
+        self._previous_excepthook = sys.excepthook
+        self._previous_thread_excepthook = threading.excepthook
+        sys.excepthook = self._on_uncaught_exception
+        threading.excepthook = self._on_uncaught_thread_exception
+
+    def is_exporting_to_app_insights(self) -> bool:
+        return self._exporting_to_app_insights
+
+    def start_span(
+            self,
+            name: str,
+            kind: SpanKind = SpanKind.INTERNAL,
+            context: Optional[Context] = None,
+    ):
+        return self.tracer.start_span(name, context=context, kind=kind)
+
+    def force_flush(self, timeout_millis: int = _DEFAULT_FLUSH_MILLISECONDS) -> bool:
+        with self._flush_gate:
+            if self._closed:
+                return True
+
+            traces = self.tracer_provider.force_flush(timeout_millis)
+            logs = self.logger_provider.force_flush(timeout_millis)
+            return bool(traces) and bool(logs)
+
+    def close(self) -> None:
+        with self._flush_gate:
+            if self._closed:
+                return
+
+            self.tracer_provider.force_flush(_DEFAULT_FLUSH_MILLISECONDS)
+            self.logger_provider.force_flush(_DEFAULT_FLUSH_MILLISECONDS)
+            self._closed = True
+
+        self.instrumentation.close()
+        self._hypertube_logger.removeHandler(self._log_handler)
+
+        try:
+            atexit.unregister(self.close)
+        except Exception:
+            pass
+
+        if sys.excepthook == self._on_uncaught_exception:
+            sys.excepthook = self._previous_excepthook
+        if threading.excepthook == self._on_uncaught_thread_exception:
+            threading.excepthook = self._previous_thread_excepthook
+
+        self.tracer_provider.shutdown()
+        self.logger_provider.shutdown()
+
+    def dispose(self) -> None:
+        self.close()
+
+    def __enter__(self) -> GraftCodeAppInsightsConnectorPipeline:
+        return self
+
+    def __exit__(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc: Optional[BaseException],
+            traceback_obj: Optional[TracebackType],
+    ) -> bool:
+        self.close()
+        return False
+
+    @staticmethod
+    def _build_exporting_sdk(
+            service_name: str,
+            connection_string: str,
+            traces_per_second: Optional[float],
+    ) -> Tuple[TracerProvider, LoggerProvider]:
+        from azure.monitor.opentelemetry.exporter import AzureMonitorLogExporter, AzureMonitorTraceExporter
+
+        sampler = ALWAYS_ON if traces_per_second is None else RateLimitedSampler(traces_per_second)
+        resource = Resource.create({"service.name": service_name})
+
+        tracer_provider = TracerProvider(resource=resource, sampler=sampler)
+        tracer_provider.add_span_processor(BatchSpanProcessor(AzureMonitorTraceExporter(
+            connection_string=connection_string, tracer_provider=tracer_provider)))
+
+        logger_provider = LoggerProvider(resource=resource)
+        logger_provider.add_log_record_processor(
+            BatchLogRecordProcessor(AzureMonitorLogExporter(connection_string=connection_string)))
+
+        return tracer_provider, logger_provider
+
+    @staticmethod
+    def _build_local_sdk(service_name: str) -> Tuple[TracerProvider, LoggerProvider]:
+        resource = Resource.create({"service.name": service_name})
+        return TracerProvider(resource=resource), LoggerProvider(resource=resource)
+
+    def _warn_about_missing_connection_string(self, options: GraftCodeAppInsightsConnectorOptions) -> None:
+        self.logger.log(LogsLevel.Warning, _MISSING_CONNECTION_STRING, self.service_name)
+
+        if not options.enable_console_logging:
+            sys.stderr.write(_MISSING_CONNECTION_STRING.replace("{ServiceName}", self.service_name) + "\n")
+
+    def _on_uncaught_exception(
+            self,
+            exc_type: Optional[Type[BaseException]],
+            exc_value: Optional[BaseException],
+            exc_traceback: Optional[TracebackType],
+    ) -> None:
+        self.force_flush()
+        self._previous_excepthook(exc_type, exc_value, exc_traceback)
+
+    def _on_uncaught_thread_exception(self, args: threading.ExceptHookArgs) -> None:
+        self.force_flush()
+        self._previous_thread_excepthook(args)

graftcode_telemetry_appinsights/GraftCodeAppInsightsLogger.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import os
+import sys
+import threading
+import time
+import traceback
+from typing import IO, Any, Optional, TextIO, Union
+
+from opentelemetry import context as otel_context
+from opentelemetry._logs import Logger as OTelLogger, LogRecord
+from opentelemetry._logs import SeverityNumber
+
+from hypertube.utils.logging.LogsLevel import LogsLevel
+
+from graftcode_telemetry_appinsights.MessageTemplate import MessageTemplate
+
+_CONSOLE_INDENT = "      "
+
+_SEVERITIES = {
+    LogsLevel.Trace: SeverityNumber.TRACE,
+    LogsLevel.Debug: SeverityNumber.DEBUG,
+    LogsLevel.Info: SeverityNumber.INFO,
+    LogsLevel.Warning: SeverityNumber.WARN,
+    LogsLevel.Error: SeverityNumber.ERROR,
+}
+
+_CONSOLE_LEVELS = {
+    LogsLevel.Trace: "trce",
+    LogsLevel.Debug: "dbug",
+    LogsLevel.Info: "info",
+    LogsLevel.Warning: "warn",
+}
+
+
+class GraftCodeAppInsightsLogger:
+
+    def __init__(
+            self,
+            category: str,
+            logger: OTelLogger,
+            minimum_level: LogsLevel,
+            console: Union[bool, TextIO, None],
+    ) -> None:
+        self._category = category
+        self._logger = logger
+        self._minimum_level = minimum_level
+        self._console = console
+        self._console_lock = threading.Lock()
+
+    def is_enabled(self, level: LogsLevel) -> bool:
+        return (level != LogsLevel.Off
+                and self._minimum_level != LogsLevel.Off
+                and level.is_at_least(self._minimum_level))
+
+    def trace(self, template: str, *args: Any) -> None:
+        self.log(LogsLevel.Trace, template, *args)
+
+    def debug(self, template: str, *args: Any) -> None:
+        self.log(LogsLevel.Debug, template, *args)
+
+    def info(self, template: str, *args: Any) -> None:
+        self.log(LogsLevel.Info, template, *args)
+
+    def warning(self, template: str, *args: Any) -> None:
+        self.log(LogsLevel.Warning, template, *args)
+
+    def error(self, exception_or_template: Union[BaseException, str], *args: Any) -> None:
+        if isinstance(exception_or_template, BaseException):
+            self.log_exception(LogsLevel.Error, exception_or_template, args[0] if args else None, *args[1:])
+        else:
+            self.log(LogsLevel.Error, exception_or_template, *args)
+
+    def log(self, level: LogsLevel, template: Optional[str], *args: Any) -> None:
+        self.log_exception(level, None, template, *args)
+
+    def log_exception(
+            self,
+            level: LogsLevel,
+            exception: Optional[BaseException],
+            template: Optional[str],
+            *args: Any,
+    ) -> None:
+        if not self.is_enabled(level):
+            return
+
+        properties: dict[str, str] = {}
+        message = MessageTemplate.render(template, args, properties)
+
+        self._emit(level, exception, template, message, properties)
+        self._write_to_console(level, exception, message)
+
+    def _emit(
+            self,
+            level: LogsLevel,
+            exception: Optional[BaseException],
+            template: Optional[str],
+            message: str,
+            properties: dict[str, str],
+    ) -> None:
+        attributes = dict(properties)
+
+        if template is not None:
+            attributes["{OriginalFormat}"] = template
+
+        if exception is not None:
+            exception_type = type(exception)
+            attributes["exception.type"] = (
+                exception_type.__module__ + "." + exception_type.__qualname__
+                if exception_type.__module__ != "builtins"
+                else exception_type.__qualname__)
+            if str(exception):
+                attributes["exception.message"] = str(exception)
+            attributes["exception.stacktrace"] = GraftCodeAppInsightsLogger._stack_trace(exception)
+
+        self._logger.emit(LogRecord(
+            timestamp=time.time_ns(),
+            context=otel_context.get_current(),
+            severity_number=_SEVERITIES[level],
+            severity_text=GraftCodeAppInsightsLogger._to_level_name(level),
+            body=message,
+            attributes=attributes))
+
+    def _write_to_console(
+            self,
+            level: LogsLevel,
+            exception: Optional[BaseException],
+            message: str,
+    ) -> None:
+        console: Optional[IO[str]] = self._console
+        if console is None:
+            return
+
+        if console is True:
+            console = sys.stdout
+
+        line = (_CONSOLE_LEVELS.get(level, "fail") + ": " + self._category + "[0]" + os.linesep
+                + _CONSOLE_INDENT + message)
+        if exception is not None:
+            line += os.linesep + GraftCodeAppInsightsLogger._stack_trace(exception).strip()
+
+        with self._console_lock:
+            console.write(line + os.linesep)
+            console.flush()
+
+    @staticmethod
+    def _stack_trace(exception: BaseException) -> str:
+        return "".join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+
+    @staticmethod
+    def _to_level_name(level: LogsLevel) -> str:
+        return "Information" if level == LogsLevel.Info else level.name

graftcode_telemetry_appinsights/GraftCodeAppInsightsRequestTelemetryMiddleware.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, MutableMapping
+
+from opentelemetry import context as otel_context
+from opentelemetry import trace
+from opentelemetry.trace import SpanKind, Status, StatusCode
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+_CONTROLLER_SUFFIX = "Controller"
+_PROPAGATOR = TraceContextTextMapPropagator()
+
+Scope = MutableMapping[str, object]
+Message = MutableMapping[str, object]
+Receive = Callable[[], Awaitable[dict]]
+Send = Callable[[Message], Awaitable[None]]
+ASGIApp = Callable[[Scope, Receive, Send], Awaitable[None]]
+
+
+class GraftCodeAppInsightsRequestTelemetryMiddleware:
+    CONTROLLER_ATTRIBUTE = "graft.controller"
+
+    def __init__(self, app: ASGIApp, telemetry: object) -> None:
+        if telemetry is None:
+            raise ValueError("telemetry must not be None")
+
+        self._app = app
+        self._telemetry = telemetry
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope.get("type") != "http":
+            await self._app(scope, receive, send)
+            return
+
+        method = str(scope.get("method", "GET"))
+        path = GraftCodeAppInsightsRequestTelemetryMiddleware._resolve_path(scope)
+        headers = {
+            name.decode("latin-1").lower(): value.decode("latin-1")
+            for name, value in scope.get("headers") or []
+        }
+
+        parent = _PROPAGATOR.extract(headers, context=otel_context.get_current())
+        span = self._telemetry.tracer.start_span(
+            GraftCodeAppInsightsRequestTelemetryMiddleware.resolve_operation_name(
+                self._telemetry.service_name, method, path, None),
+            context=parent,
+            kind=SpanKind.SERVER)
+
+        if span.is_recording():
+            span.set_attribute("http.method", method)
+            span.set_attribute("http.target", path)
+
+        status: dict[str, object | None] = {"code": None}
+
+        async def send_with_status(message: Message) -> None:
+            if message.get("type") == "http.response.start":
+                status["code"] = message.get("status")
+            await send(message)
+
+        token = otel_context.attach(trace.set_span_in_context(span))
+        try:
+            await self._app(scope, receive, send_with_status)
+
+            code = int(status["code"]) if status["code"] is not None else 200
+            span.set_attribute("http.status_code", code)
+            if code >= 500:
+                span.set_status(Status(StatusCode.ERROR))
+        except Exception as exception:
+            span.set_status(Status(StatusCode.ERROR, str(exception)))
+            span.record_exception(exception)
+            raise
+        finally:
+            controller = GraftCodeAppInsightsRequestTelemetryMiddleware.resolve_controller_name(scope)
+            if controller is not None:
+                span.update_name(GraftCodeAppInsightsRequestTelemetryMiddleware.resolve_operation_name(
+                    self._telemetry.service_name, method, path, controller))
+
+            otel_context.detach(token)
+            span.end()
+
+    @staticmethod
+    def resolve_operation_name(service_name: str, method: str, path: str | None, controller: str | None) -> str:
+        if controller is not None and controller.strip():
+            return service_name + "." + controller
+
+        return service_name + " " + method + " " + (path or "/")
+
+    @staticmethod
+    def resolve_controller_name(scope: Scope) -> str | None:
+        state = scope.get("state")
+        explicit = state.get(GraftCodeAppInsightsRequestTelemetryMiddleware.CONTROLLER_ATTRIBUTE) \
+            if isinstance(state, dict) else None
+        if isinstance(explicit, str) and explicit.strip():
+            return explicit
+
+        owner = GraftCodeAppInsightsRequestTelemetryMiddleware._owner_name(scope.get("endpoint"))
+        if owner is None:
+            return None
+
+        if owner.endswith(_CONTROLLER_SUFFIX) and len(owner) > len(_CONTROLLER_SUFFIX):
+            return owner[:-len(_CONTROLLER_SUFFIX)]
+        return owner
+
+    @staticmethod
+    def _owner_name(endpoint: object) -> str | None:
+        if endpoint is None:
+            return None
+
+        bound_to = getattr(endpoint, "__self__", None)
+        if bound_to is not None:
+            return (bound_to if isinstance(bound_to, type) else type(bound_to)).__name__
+
+        qualified = getattr(endpoint, "__qualname__", "")
+        parts = [part for part in qualified.split(".") if part != "<locals>"]
+        return parts[-2] if len(parts) >= 2 else None
+
+    @staticmethod
+    def _resolve_path(scope: Scope) -> str:
+        path = str(scope.get("path") or "/")
+        root_path = str(scope.get("root_path") or "")
+        if root_path and path.startswith(root_path):
+            path = path[len(root_path):]
+        return path or "/"

graftcode_telemetry_appinsights/MessageTemplate.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Sequence
+
+_NULL_VALUE = "(null)"
+
+
+class MessageTemplate:
+
+    @staticmethod
+    def render(template: Optional[str], args: Optional[Sequence[Any]], properties: Dict[str, str]) -> str:
+        if template is None:
+            return ""
+
+        values = args or ()
+        builder: List[str] = []
+        arg_index = 0
+        length = len(template)
+        i = 0
+
+        while i < length:
+            character = template[i]
+
+            if character in "{}" and i + 1 < length and template[i + 1] == character:
+                builder.append(character)
+                i += 2
+                continue
+
+            closing_index = template.find("}", i + 1) if character == "{" else -1
+            if closing_index < 0 or arg_index >= len(values):
+                builder.append(character)
+                i += 1
+                continue
+
+            value = MessageTemplate._format(values[arg_index])
+            arg_index += 1
+            builder.append(value)
+
+            name = MessageTemplate._property_name(template[i + 1:closing_index])
+            if name:
+                properties[name] = value
+
+            i = closing_index + 1
+
+        return "".join(builder)
+
+    @staticmethod
+    def _property_name(placeholder: str) -> str:
+        end = len(placeholder)
+        for index, character in enumerate(placeholder):
+            if character in ",:":
+                end = index
+                break
+
+        name = placeholder[:end].strip()
+        if name.startswith("@") or name.startswith("$"):
+            name = name[1:]
+
+        return name
+
+    @staticmethod
+    def _format(value: Any) -> str:
+        if value is None:
+            return _NULL_VALUE
+
+        try:
+            return str(value)
+        except Exception:
+            value_type = type(value)
+            return value_type.__module__ + "." + value_type.__qualname__

graftcode_telemetry_appinsights/RateLimitedSampler.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import threading
+import time
+from typing import Optional
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace.sampling import Decision, Sampler, SamplingResult
+from opentelemetry.trace import Link, SpanKind
+from opentelemetry.trace.span import TraceState
+
+
+class RateLimitedSampler(Sampler):
+
+    def __init__(self, traces_per_second: float) -> None:
+        self._traces_per_second = traces_per_second
+        self._capacity = max(1.0, traces_per_second)
+        self._tokens = self._capacity
+        self._last_refill = time.monotonic()
+        self._lock = threading.Lock()
+
+    def should_sample(
+            self,
+            parent_context: Optional[Context],
+            trace_id: int,
+            name: str,
+            kind: Optional[SpanKind] = None,
+            attributes: Optional[dict] = None,
+            links: Optional[tuple[Link, ...]] = None,
+            trace_state: Optional[TraceState] = None,
+    ) -> SamplingResult:
+        decision = Decision.RECORD_AND_SAMPLE if self._try_acquire() else Decision.DROP
+        return SamplingResult(decision, attributes if decision == Decision.RECORD_AND_SAMPLE else None, trace_state)
+
+    def get_description(self) -> str:
+        return "RateLimitedSampler{" + str(self._traces_per_second) + "}"
+
+    def _try_acquire(self) -> bool:
+        with self._lock:
+            now = time.monotonic()
+            self._tokens = min(self._capacity, self._tokens + (now - self._last_refill) * self._traces_per_second)
+            self._last_refill = now
+
+            if self._tokens < 1.0:
+                return False
+
+            self._tokens -= 1.0
+            return True

graftcode_telemetry_appinsights/__init__.py

@@ -0,0 +1,15 @@
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnector import GraftCodeAppInsightsConnector
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnectorOptions import GraftCodeAppInsightsConnectorOptions
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsConnectorPipeline import GraftCodeAppInsightsConnectorPipeline
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsLogger import GraftCodeAppInsightsLogger
+from graftcode_telemetry_appinsights.GraftCodeAppInsightsRequestTelemetryMiddleware import (
+    GraftCodeAppInsightsRequestTelemetryMiddleware,
+)
+
+__all__ = [
+    "GraftCodeAppInsightsConnector",
+    "GraftCodeAppInsightsConnectorOptions",
+    "GraftCodeAppInsightsConnectorPipeline",
+    "GraftCodeAppInsightsLogger",
+    "GraftCodeAppInsightsRequestTelemetryMiddleware",
+]

graftcode_telemetry_appinsights-1.0.0.dist-info/METADATA

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: graftcode-telemetry-appinsights
+Version: 1.0.0
+Summary: Application Insights connector for Graftcode / Hypertube telemetry in Python
+Author-email: "Graftcode S.A." <support@graftcode.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.39
+Requires-Dist: opentelemetry-sdk>=1.39
+Requires-Dist: azure-monitor-opentelemetry-exporter>=1.0.0b40
+Requires-Dist: graftcode-instrumentation>=1.0.0
+Requires-Dist: hypertube-python-sdk>=3.0.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: starlette; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+
+# GraftCode App Insights Connector (Python)
+
+Configures Application Insights for an application, together with the Graft bridge spans, in one call. It is a port of the .NET (`GraftCode.Netcore.Telemetry.AppInsightsConnector`) and Java (`com.graftcode.telemetry.appinsights`) connectors.
+
+```python
+from graftcode_telemetry_appinsights import GraftCodeAppInsightsConnector
+
+with GraftCodeAppInsightsConnector.start("MyService") as telemetry:
+    span = telemetry.start_span("MyOperation")
+    telemetry.logger.info("My operation started {Step}", "one")
+    span.end()
+```
+
+The connector reads `APPLICATIONINSIGHTS_CONNECTION_STRING` and exports traces and logs with the Azure Monitor exporter (`azure-monitor-opentelemetry-exporter`). It also attaches `graftcode-instrumentation`, so Hypertube calls produce `Graftcode` spans and Hypertube log lines go to the same pipeline. You can configure an explicit connection string with a callback or an options object:
+
+```python
+from graftcode_telemetry_appinsights import GraftCodeAppInsightsConnector, GraftCodeAppInsightsConnectorOptions
+
+def configure(options):
+    options.service_name = "MyService"
+    options.connection_string = settings["ApplicationInsights:ConnectionString"]
+
+telemetry = GraftCodeAppInsightsConnector.start(configure)
+telemetry = GraftCodeAppInsightsConnector.start(GraftCodeAppInsightsConnectorOptions(service_name="MyService"))
+```
+
+| Option | Default |
+|--------|---------|
+| `service_name` | required; becomes `service.name` (the App Insights cloud role) and the tracer/logger name |
+| `connection_string` | falls back to `APPLICATIONINSIGHTS_CONNECTION_STRING` |
+| `minimum_log_level` | `LogsLevel.Info`; applies to the connector logger and to forwarded Hypertube lines |
+| `traces_per_second` | `None` (every trace is kept) |
+| `enable_console_logging` | `True` |
+
+## Pipeline (`GraftCodeAppInsightsConnectorPipeline`)
+
+| Member | Purpose |
+|--------|---------|
+| `tracer`, `start_span(name, kind=INTERNAL, context=None)` | spans for the application |
+| `logger` | `GraftCodeAppInsightsLogger` (`trace`, `debug`, `info`, `warning`, `error`, `log`) |
+| `instrumentation` | the attached `GraftcodeInstrumentation` |
+| `force_flush(timeout_millis=5000)` | flushes traces and logs |
+| `close()` / context manager | flushes, detaches the instrumentation, and shuts the providers down; calling it twice is safe |
+| `is_exporting_to_app_insights()` | `False` when no connection string was resolved |
+
+The OpenTelemetry providers are not registered as globals, which matches the Java connector. Use `pipeline.tracer` or `pipeline.start_span` for application spans.
+
+## Logger
+
+The logger uses the same message templates as the .NET and Java connectors:
+
+- `{Name}` placeholders are filled positionally. `{{` and `}}` escape braces, and format specifiers (`{Count:D3}`) are ignored. `None` renders as `(null)`.
+- Each placeholder becomes a log attribute. The raw template is stored as `{OriginalFormat}`.
+- Records are correlated with the current span.
+- Console output follows the .NET console layout:
+
+```
+info: TestGgPythonWebApi[0]
+      Caller after Graft call Result=fetched
+```
+
+To log an exception, pass it first: `logger.error(exception, "failed {Step}", "fetch")`. It is attached as `exception.type`, `exception.message` and `exception.stacktrace`.
+
+Hypertube's own lines reach App Insights through the standard-library logger `Hypertube`. The pipeline sets that logger's level from `minimum_log_level` and adds a handler that emits through the OpenTelemetry logs API (instrumentation scope `Hypertube`).
+
+## Request telemetry (ASGI)
+
+Add the middleware to FastAPI or Starlette. It plays the role of `UseGraftCodeAppInsightsConnectorRequestTelemetry` in .NET and the servlet filter in Java:
+
+```python
+app.add_middleware(GraftCodeAppInsightsRequestTelemetryMiddleware, telemetry=telemetry)
+```
+
+Each HTTP request gets a `SERVER` span that is current while the endpoint runs:
+
+- **Parent:** the incoming W3C `traceparent`, when present.
+- **Attributes:** `http.method`, `http.target` and `http.status_code`. A status of 500 or higher marks the span as failed, and exceptions are recorded and re-raised. The path goes in `http.target` rather than `http.route` (as .NET and Java use) because the Python Azure Monitor exporter replaces the request name with `METHOD route` whenever `http.route` or a full URL is present; with `http.target` the request keeps the controller-based name, as in .NET and Java.
+- **Name:** `{ServiceName}.{controller}` when the routed endpoint belongs to a class, for example a `FetchController.fetch` endpoint gives `TestGgPythonWebApi.Fetch`. An explicit name can be set in `scope["state"]["graft.controller"]`. Otherwise the name is `{ServiceName} {METHOD} {path}`.
+
+Synchronous endpoints run in Starlette's thread pool with a copy of the context, so Graft calls made there share the request's trace.
+
+## Sampling
+
+Every trace is kept by default (`ALWAYS_ON`); the reason is the same as in .NET and Java. Set `traces_per_second` to opt into a token-bucket `RateLimitedSampler`.
+
+## Flushing
+
+The pipeline flushes on `close()`, at interpreter exit (`atexit`), and on unhandled exceptions; both `sys.excepthook` and `threading.excepthook` are chained. Short-lived processes should still call `force_flush()` before exiting.
+
+## Diagnosing missing telemetry
+
+When no connection string is resolved, `is_exporting_to_app_insights()` returns `False` and telemetry stays local. The connector then logs `Application Insights telemetry for {ServiceName} is disabled: no connection string was configured. ...`.
+
+## Tests
+
+```powershell
+$env:PYTHONPATH = "<HYPERTUBE>\src\python;<graftcode-extensions>\observability\Instrumentation\python"
+python -m pip install -e .[dev]
+python -m pytest
+```

graftcode_telemetry_appinsights-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+graftcode_telemetry_appinsights/GraftCodeAppInsightsConnector.py,sha256=8KzytiE59VTHEN--003tiHZgwLkIvM9Y0g1TPy6Ngwg,1226
+graftcode_telemetry_appinsights/GraftCodeAppInsightsConnectorOptions.py,sha256=YDNV1-hXKifji2-X6OXqrj0-bQLYwdfkkrPaF99jLNw,1915
+graftcode_telemetry_appinsights/GraftCodeAppInsightsConnectorPipeline.py,sha256=fXFIZW_rmPXOhJWjskvyg95h47iKxTcKFX85n4F8S2o,9863
+graftcode_telemetry_appinsights/GraftCodeAppInsightsLogger.py,sha256=HgkzvPO2SpSWiOdBxTVxPCuYGxaGTJkbd-YZxIqZifI,5081
+graftcode_telemetry_appinsights/GraftCodeAppInsightsRequestTelemetryMiddleware.py,sha256=ftFxIYOsp5fbrQKKoBi6oC8JAAQC6y9b5xSb4TVuK6Y,4872
+graftcode_telemetry_appinsights/MessageTemplate.py,sha256=MoUoFl0lyxjJ4CQEOUY2OYkH2fHvIDYj6-fIoT7EFzo,1936
+graftcode_telemetry_appinsights/RateLimitedSampler.py,sha256=SowLd5dn_soTMbHaLTkoD550uhJaNrRZ-WQh47CrVI4,1684
+graftcode_telemetry_appinsights/__init__.py,sha256=ZcYdcsHaqLWtNRaxzpsu-qRdyfGuaz4Wzvg27AA46QU,816
+graftcode_telemetry_appinsights-1.0.0.dist-info/METADATA,sha256=F_KujYE9-7rs8ZonZZ2Vmi_oG8NIeoUL7QGxs3ndwcI,6446
+graftcode_telemetry_appinsights-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+graftcode_telemetry_appinsights-1.0.0.dist-info/top_level.txt,sha256=DzD7wxkOZAEyRFI75D6HWBwAV8fjGU3wFzOA7vG8BNY,32
+graftcode_telemetry_appinsights-1.0.0.dist-info/RECORD,,

graftcode_telemetry_appinsights-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

graftcode_telemetry_appinsights-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graftcode_telemetry_appinsights