Metrics API¶
general_manager.metrics.graphql.GraphQLMetricsBackend ¶
Bases: Protocol
Backend contract for request and resolver-level GraphQL metrics.
record_request ¶
record_request(
*, duration, operation_name, operation_type, status
)
Record one GraphQL request.
Inputs are expected to be normalized labels. operation_type is query, mutation, subscription, or unknown; status is success or error.
record_error ¶
record_error(*, operation_name, code)
Record one GraphQL error for a normalized operation/code label.
record_resolver_duration ¶
record_resolver_duration(*, field_name, duration)
Record one resolver duration observation.
record_resolver_error ¶
record_resolver_error(*, field_name)
Record one resolver exception for a normalized field label.
general_manager.metrics.graphql.GraphQLMetricsSettings dataclass ¶
Resolved GraphQL metrics settings used by the instrumentation helpers.
general_manager.metrics.graphql.NoopGraphQLMetricsBackend ¶
general_manager.metrics.graphql.PrometheusGraphQLMetricsBackend ¶
Prometheus backend that records GraphQL request and resolver metrics.
Collectors are registered in the default Prometheus registry on first construction and reused by later instances in the same process. Recording methods clamp negative, NaN, and infinite durations to 0.0, but otherwise pass labels through as supplied. Prometheus registration and recording exceptions are not caught by this backend; callers that need isolation should catch them at the call site.
record_request ¶
record_request(
*, duration, operation_name, operation_type, status
)
Increment request count and observe non-negative request duration.
record_error ¶
record_error(*, operation_name, code)
Increment the GraphQL error counter for a normalized code label.
record_resolver_duration ¶
record_resolver_duration(*, field_name, duration)
Observe non-negative resolver duration for a normalized field label.
record_resolver_error ¶
record_resolver_error(*, field_name)
Increment the resolver error counter for a normalized field label.
general_manager.metrics.graphql.GraphQLResolverTimingMiddleware ¶
Graphene middleware that records resolver duration and error metrics.
resolve ¶
resolve(next_, root, info, **args)
Resolve one field and record duration/error metrics.
The middleware supports synchronous return values and awaitables. Metric backend exceptions are caught and logged at debug level so resolver execution is not changed by metrics failures. Exceptions from the resolver itself are recorded and then re-raised.
general_manager.metrics.graphql.get_graphql_metrics_backend ¶
get_graphql_metrics_backend()
Return the cached configured GraphQL metrics backend.
Disabled metrics, GRAPHQL_METRICS_BACKEND="noop", and unknown backend names use NoopGraphQLMetricsBackend. Unknown names log a warning; noop does not. The Prometheus backend is created only when metrics are enabled and GRAPHQL_METRICS_BACKEND resolves to prometheus; if prometheus-client is unavailable, the helper logs a warning and falls back to the no-op backend. Backend construction errors other than import failure propagate.
general_manager.metrics.graphql.reset_graphql_metrics_backend_for_tests ¶
reset_graphql_metrics_backend_for_tests()
Clear the cached metrics backend for settings-isolated tests.
general_manager.metrics.graphql.build_graphql_middleware ¶
build_graphql_middleware()
Return Graphene middleware with resolver timing attached when enabled.
The helper copies graphene_settings.MIDDLEWARE into a new list. If metrics or resolver timing are disabled, the copied list is returned unchanged. An existing GraphQLResolverTimingMiddleware class or instance is not added a second time.
general_manager.metrics.graphql.graphql_metrics_enabled ¶
graphql_metrics_enabled()
Return whether request-level GraphQL metrics are enabled in settings.
general_manager.metrics.graphql.graphql_metrics_resolver_timing_enabled ¶
graphql_metrics_resolver_timing_enabled()
Return whether resolver timing metrics should be attached.
general_manager.metrics.graphql.normalize_operation_name ¶
normalize_operation_name(operation_name)
Normalize a GraphQL operation name for use as a metric label.
None, empty, and punctuation-only values become unknown. Values are transliterated to ASCII, stripped, sanitized to [0-9A-Za-z_.-], and truncated to GRAPHQL_METRICS_MAX_OPERATION_LENGTH when positive. Allowlist checks run after normalization. With hash policy enabled, non-allowlisted raw operation names become op_<sha256-prefix>, where the SHA-256 hex digest prefix is eight characters before the op_ prefix is truncated by a positive GRAPHQL_METRICS_MAX_OPERATION_LENGTH. Unrecognized operation policies behave like unknown.
general_manager.metrics.graphql.normalize_operation_type ¶
normalize_operation_type(operation_type)
Normalize a GraphQL operation type for use as a metric label.
query, mutation, and subscription are the expected GraphQL values, but other non-empty strings are sanitized instead of rejected. Missing values become unknown.
general_manager.metrics.graphql.normalize_error_code ¶
normalize_error_code(code)
Normalize a GraphQL error code value for use as a metric label.
Empty and punctuation-only values become unknown. Values use the same ASCII/sanitize rules as operation names and are truncated to 64 characters.
general_manager.metrics.graphql.normalize_field_name ¶
normalize_field_name(field_name)
Normalize a GraphQL resolver field name using the field-label length limit.
Empty and punctuation-only values become unknown. Values use the same ASCII/sanitize rules as operation names and are truncated to GRAPHQL_METRICS_MAX_LABEL_LENGTH when positive.
general_manager.metrics.graphql.resolve_operation_type ¶
resolve_operation_type(query, operation_name)
Parse a GraphQL document and return the selected operation type label.
Invalid, missing, or ambiguous documents return unknown instead of raising parser errors. Unexpected runtime errors from GraphQL parsing helpers are not caught.
general_manager.metrics.graphql.extract_error_code ¶
extract_error_code(error)
Return a normalized GraphQL error extension code, or unknown.
Only direct GraphQLError instances are inspected. Wrapped/original exceptions are not unwrapped.