telemetry

The telemetry configuration is defined as follows:

Runtime Configuration

Runtime Configuration

telemetry:
  export:
    # oneof:
    otlp:
      url: string
      headers:
        - key: string
          value: string
    prometheus:
      path: string
      format: text # protobuf
    stdout:
      pretty: boolean
  requestHeaders:
    - string

The telemetry configuration facilitates seamless integration with OpenTelemetry, enhancing the observability of your GraphQL services powered by GQLForge. By leveraging this configuration, developers gain access to valuable insights into the performance and behavior of their applications.

Traces

Here are the traces that are captured by the telemetry configuration:

Trace Name	Description
request	Captures the span for processing the HTTP request on the server side, providing foundational observability.
graphQL	Only for GraphQL ingress. Span for processing GraphQL call
REST <http_method> <http_route>	Only for REST ingress. Span for processing REST API call
<field_name>	Denotes spans for fields with defined resolvers, offering insights into field names and execution times for resolver logic.
<expr_name>	Nested within the <field_name> spans, these granulated spans detail the execution of expressions in resolving a field, highlighting the hierarchical execution pattern of nested expressions.
upstream_request	Request that were made from gqlforge service to upstream

Metrics

The telemetry configuration also captures the following metrics:

Metric	Description
cache.hit_rate	Reflects the cache hit rate for the cache powered by the @cache directive
http.server.request.count	Counts the number of incoming requests made to specific route. Optionally enriched with selected headers by requestHeaders
http.client.request.count	Counts the number of outgoing requests to specific upstream

export

The export field defines how the open-telemetry data should be exported and in which format. The following are the supported formats:

otlp

Utilizes the OTLP format to export telemetry data to backend systems, supported by most modern tracing and analytics platforms. Here is an example using [honeycomb.io]:

telemetry:
  export:
    otlp:
      url: "https://api.honeycomb.io:443"
      headers:
        - key: "x-honeycomb-team"
          value: "{{.env.HONEYCOMB_API_KEY}}"
        - key: "x-honeycomb-dataset"
          value: "gqlforge"

You can configure the OTLP exporter with the following options:

Field	Description
url	Defines the URL for the OTLP Collector.
headers	Sets additional headers for requests to the OTLP Collector.

prometheus

Facilitates metrics export in a Prometheus compatible format, providing a dedicated endpoint for metrics.

telemetry:
  export:
    prometheus:
      path: "/metrics"

You can configure the Prometheus exporter with the following options:

Field	Description
path	Designates the endpoint path for Prometheus metrics, defaulting to /metrics.
format	Controls the format viz. text or protobuf, for sending data to Prometheus.

stdout

Outputs all telemetry data to stdout, ideal for testing or local development environments.

telemetry:
  export:
    stdout:
      pretty: true

You can configure the stdout exporter with the following options:

Field	Description
pretty	Enables formatted output of telemetry data for enhanced readability.

requestHeaders

Specifies list of headers of ingress request the value of which will be sent to the telemetry as attributes.

telemetry:
  requestHeaders:
    - "X-User-Id"

By integrating the telemetry configuration into your GraphQL schema, you empower your development teams with critical insights into application performance, enabling proactive optimization and maintenance.