Skip to main content

@telemetry

The @telemetry directive facilitates seamless integration with OpenTelemetry, enhancing the observability of your GraphQL services powered by Tailcall. By leveraging this directive, 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 directive:

Trace NameDescription
requestCaptures the span for processing the HTTP request on the server side, providing foundational observability.
graphQLOnly 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_requestRequest that were made from tailcall service to upstream

Metrics​

The @telemetry directive also captures the following metrics:

MetricDescription
cache.hit_rateReflects the cache hit rate for the cache powered by the @cache directive
http.server.request.countCounts the number of incoming requests made to specific route. Optionally enriched with selected headers by requestHeaders
http.client.request.countCounts 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]:

schema
  @telemetry(
    export: {
      otlp: {
        url: "https://api.honeycomb.io:443"
        headers: [
          {
            key: "x-honeycomb-team"
            value: "{{.env.HONEYCOMB_API_KEY}}"
          }
          {key: "x-honeycomb-dataset", value: "tailcall"}
        ]
      }
    }
  ) {
  query: Query
}

You can configure the OTLP exporter with the following options:

FieldDescription
urlDefines the URL for the OTLP Collector.
headersSets additional headers for requests to the OTLP Collector.

prometheus​

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

schema
  @telemetry(export: {prometheus: {path: "/metrics"}}) {
  query: Query
}

You can configure the Prometheus exporter with the following options:

FieldDescription
pathDesignates the endpoint path for Prometheus metrics, defaulting to /metrics.
formatControls 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.

schema @telemetry(export: {stdout: {pretty: true}}) {
  query: Query
}

You can configure the stdout exporter with the following options:

FieldDescription
prettyEnables 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.

schema @telemetry(requestHeaders: ["X-User-Id"]) {
  query: Query
}

apollo​

Facilitates seamless integration with Apollo Studio, enhancing the observability of GraphQL services. By leveraging this field, developers gain access to valuable insights into the performance and behavior of their GraphQL APIs.

schema
  @telemetry(
    export: {
      otlp: {
        api_key: "{{.env.APOLLO_API_KEY}}"
        graph_ref: "graph-id@current"
        platform: "website.com"
        version: "1.0.0"
      }
    }
  ) {
  query: Query
}

You can configure the apollo exporter with the following options:

FieldDescription
api_keyThe API Key generated from Apollo Studio.
graph_refThe Graph Ref, which is the graph_id and the variant concatenated using @(i.e. <graph_id>@<variant>)
platformAn arbitrary value which can contain the name of your website or some other value to identify your deployment uniqely, in case you have multiple deployments.
versionVersion of Apollo which is being used.

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