|
| 1 | +"""Utility functions for recording runtime errors to OpenTelemetry traces.""" |
| 2 | + |
| 3 | +from typing import Any |
| 4 | + |
| 5 | +from opentelemetry import trace |
| 6 | +from opentelemetry.trace import Status, StatusCode |
| 7 | + |
| 8 | + |
| 9 | +def record_http_error( |
| 10 | + status_code: int, |
| 11 | + method: str, |
| 12 | + path: str, |
| 13 | + operation: str = "http_request", |
| 14 | + component: str = "golf", |
| 15 | + error_message: str | None = None, |
| 16 | + attributes: dict[str, Any] | None = None, |
| 17 | +) -> None: |
| 18 | + """Record an HTTP error response to the current trace span. |
| 19 | +
|
| 20 | + This function safely records HTTP errors (non-200/202 responses) to the current |
| 21 | + OpenTelemetry span. Use this for capturing failed OAuth flows, health check |
| 22 | + failures, or any other HTTP endpoint that returns an error status. |
| 23 | +
|
| 24 | + Args: |
| 25 | + status_code: The HTTP status code (e.g., 401, 403, 500, 503) |
| 26 | + method: HTTP method (GET, POST, etc.) |
| 27 | + path: Request path (e.g., "/oauth/token", "/health") |
| 28 | + operation: Name of the operation (e.g., "oauth_token", "health_check") |
| 29 | + component: Source component (default: "golf") |
| 30 | + error_message: Optional error message to include |
| 31 | + attributes: Optional additional attributes to add to the span |
| 32 | +
|
| 33 | + Example: |
| 34 | + if response.status_code == 401: |
| 35 | + record_http_error(401, "POST", "/oauth/token", "oauth_token", |
| 36 | + error_message="Invalid credentials") |
| 37 | + """ |
| 38 | + span = trace.get_current_span() |
| 39 | + |
| 40 | + # Safety check: no span or span not recording |
| 41 | + if span is None or not span.is_recording(): |
| 42 | + return |
| 43 | + |
| 44 | + # Only record errors for 4xx and 5xx status codes |
| 45 | + if status_code < 400: |
| 46 | + return |
| 47 | + |
| 48 | + # Determine error category |
| 49 | + error_category = "client_error" if status_code < 500 else "server_error" |
| 50 | + |
| 51 | + # Build event attributes |
| 52 | + event_attrs: dict[str, Any] = { |
| 53 | + "http.status_code": status_code, |
| 54 | + "http.method": method, |
| 55 | + "http.path": path, |
| 56 | + "error.category": error_category, |
| 57 | + "error.source": component, |
| 58 | + "operation": operation, |
| 59 | + } |
| 60 | + |
| 61 | + if error_message: |
| 62 | + event_attrs["error.message"] = error_message |
| 63 | + |
| 64 | + if attributes: |
| 65 | + event_attrs.update({f"error.{k}": str(v) for k, v in attributes.items()}) |
| 66 | + |
| 67 | + # Set span status to ERROR |
| 68 | + status_description = f"{component}.{operation}: HTTP {status_code}" |
| 69 | + if error_message: |
| 70 | + status_description += f" - {error_message}" |
| 71 | + span.set_status(Status(StatusCode.ERROR, status_description)) |
| 72 | + |
| 73 | + # Add HTTP status code attribute |
| 74 | + span.set_attribute("http.status_code", status_code) |
| 75 | + |
| 76 | + # Add an error event with structured attributes |
| 77 | + span.add_event(f"{component}.http_error", event_attrs) |
| 78 | + |
| 79 | + |
| 80 | +def record_runtime_error( |
| 81 | + error: Exception, |
| 82 | + operation: str, |
| 83 | + component: str = "golf", |
| 84 | + attributes: dict[str, Any] | None = None, |
| 85 | +) -> None: |
| 86 | + """Record a runtime error to the current trace span. |
| 87 | +
|
| 88 | + This function safely records an error to the current OpenTelemetry span, |
| 89 | + if one exists and is recording. It's designed to be called from generated |
| 90 | + server code or extension libraries like golf-mcp-enterprise. |
| 91 | +
|
| 92 | + Args: |
| 93 | + error: The exception that occurred |
| 94 | + operation: Name of the operation that failed (e.g., "startup_script", "health_check") |
| 95 | + component: Source component (default: "golf", could be "golf-mcp-enterprise") |
| 96 | + attributes: Optional additional attributes to add to the span |
| 97 | +
|
| 98 | + Example: |
| 99 | + try: |
| 100 | + run_startup_script() |
| 101 | + except Exception as e: |
| 102 | + record_runtime_error(e, "startup_script") |
| 103 | + print(f"Startup failed: {e}", file=sys.stderr) |
| 104 | + """ |
| 105 | + span = trace.get_current_span() |
| 106 | + |
| 107 | + # Safety check: no span or span not recording |
| 108 | + if span is None or not span.is_recording(): |
| 109 | + return |
| 110 | + |
| 111 | + # Record the exception with escaped=True since we're not suppressing it |
| 112 | + extra_attrs = { |
| 113 | + "error.source": component, |
| 114 | + "error.operation": operation, |
| 115 | + } |
| 116 | + if attributes: |
| 117 | + extra_attrs.update({f"error.{k}": str(v) for k, v in attributes.items()}) |
| 118 | + |
| 119 | + span.record_exception(error, attributes=extra_attrs, escaped=True) |
| 120 | + |
| 121 | + # Set span status to ERROR |
| 122 | + span.set_status(Status(StatusCode.ERROR, f"{component}.{operation}: {type(error).__name__}: {error}")) |
| 123 | + |
| 124 | + # Add an error event with structured attributes |
| 125 | + span.add_event( |
| 126 | + f"{component}.runtime_error", |
| 127 | + { |
| 128 | + "operation": operation, |
| 129 | + "error.type": type(error).__name__, |
| 130 | + "error.message": str(error), |
| 131 | + }, |
| 132 | + ) |
0 commit comments