OpenTelemetry

This API is available since Fedify 1.3.0.

OpenTelemetry is a standardized set of APIs, libraries, agents, and instrumentation to provide observability to your applications. Fedify supports OpenTelemetry for tracing. This document explains how to use OpenTelemetry with Fedify.

Setting up OpenTelemetry

To trace your Fedify application with OpenTelemetry, you need to set up the OpenTelemetry SDK. First of all, you need to install the OpenTelemetry SDK and the tracer exporter you want to use. For example, if you want to use the trace exporter for OTLP (http/protobuf), you should install the following packages:

Deno

deno add npm:@opentelemetry/sdk-node npm:@opentelemetry/exporter-trace-otlp-proto

Node.js

npm add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

Bun

bun add @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-proto

Then you can set up the OpenTelemetry SDK in your Fedify application. Here is an example code snippet to set up the OpenTelemetry SDK with the OTLP trace exporter:

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";

const sdk = new NodeSDK({
  serviceName: "my-fedify-app",
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4317",
    headers: { "x-some-header": "some-value" }
  }),
});

sdk.start();

CAUTION

The above code which sets up the OpenTelemetry SDK needs to be executed before the Fedify server starts. Otherwise, the tracing may not work as expected.

Explicit TracerProvider configuration

The createFederation() function accepts the tracerProvider option to explicitly configure the TracerProvider for the OpenTelemetry SDK. Note that if it's omitted, Fedify will use the global default TracerProvider provided by the OpenTelemetry SDK.

For example, if you want to use Sentry as the trace exporter, you can set up the Sentry SDK and pass the TracerProvider provided by the Sentry SDK to the createFederation() function:

import { createFederation } from "@fedify/fedify";
import { getClient } from "@sentry/node";

const federation = createFederation<void>({
  // Omitted for brevity; see the related section for details.
  tracerProvider: getClient()?.traceProvider,
});

CAUTION

The Sentry SDK's OpenTelemetry integration is available since @sentry/node 8.0.0, and it's not available yet in @sentry/deno or @sentry/bun as of November 2024.

For more information about the Sentry SDK's OpenTelemetry integration, please refer to the OpenTelemetry Support section in the Sentry SDK docs.

Instrumented spans

Fedify automatically instruments the following operations with OpenTelemetry spans:

Span name	Span kind	Description
{method} {template}	Server	Serves the incoming HTTP request.
activitypub.dispatch_actor	Server	Dispatches the ActivityPub actor.
activitypub.dispatch_actor_key_pairs	Server	Dispatches the ActivityPub actor key pairs.
activitypub.dispatch_collection {collection}	Server	Dispatches the ActivityPub collection.
activitypub.dispatch_collection_page {collection}	Server	Dispatches the ActivityPub collection page.
activitypub.dispatch_inbox_listener {type}	Internal	Dispatches the ActivityPub inbox listener.
activitypub.dispatch_object	Server	Dispatches the Activity Streams object.
activitypub.fetch_key	Client	Fetches the public keys for the actor.
activitypub.get_actor_handle	Client	Resolves the actor handle.
activitypub.inbox	Consumer	Dequeues the ActivityPub activity to receive.
activitypub.inbox	Internal	Manually routes the ActivityPub activity.
activitypub.inbox	Producer	Enqueues the ActivityPub activity to receive.
activitypub.inbox	Server	Receives the ActivityPub activity.
activitypub.lookup_object	Client	Looks up the Activity Streams object.
activitypub.outbox	Client	Sends the ActivityPub activity.
activitypub.outbox	Consumer	Dequeues the ActivityPub activity to send.
activitypub.outbox	Producer	Enqueues the ActivityPub activity to send.
activitypub.parse_object	Internal	Parses the Activity Streams object.
activitypub.send_activity	Client	Sends the ActivityPub activity.
http_signatures.sign	Internal	Signs the HTTP request.
http_signatures.verify	Internal	Verifies the HTTP request signature.
ld_signatures.sign	Internal	Makes the Linked Data signature.
ld_signatures.verify	Internal	Verifies the Linked Data signature.
object_integrity_proofs.sign	Internal	Makes the object integrity proof.
object_integrity_proofs.verify	Internal	Verifies the object integrity proof.
webfinger.handle	Server	Handles the WebFinger request.
webfinger.lookup	Client	Looks up the WebFinger resource.

More operations will be instrumented in the future releases.

Semantic attributes for ActivityPub

The OpenTelemetry Semantic Conventions currently do not have a specification for ActivityPub as of November 2024. However, Fedify provides a set of semantic attributes for ActivityPub. The following table shows the semantic attributes for ActivityPub:

Attribute	Type	Description	Example
activitypub.activity.id	string	The URI of the activity object.	"https://example.com/activity/1"
activitypub.activity.type	string[]	The qualified URI(s) of the activity type(s).	["https://www.w3.org/ns/activitystreams#Create"]
activitypub.activity.to	string[]	The URI(s) of the recipient collections/actors of the activity.	["https://example.com/1/followers/2"]
activitypub.activity.cc	string[]	The URI(s) of the carbon-copied recipient collections/actors of the activity.	["https://www.w3.org/ns/activitystreams#Public"]
activitypub.activity.bto	string[]	The URI(s) of the blind recipient collections/actors of the activity.	["https://example.com/1/followers/2"]
activitypub.activity.bcc	string[]	The URI(s) of the blind carbon-copied recipient collections/actors of the activity.	["https://www.w3.org/ns/activitystreams#Public"]
activitypub.activity.retries	int	The ordinal number of activity resending attempt (if and only if it's retried).	3
activitypub.actor.id	string	The URI of the actor object.	"https://example.com/actor/1"
activitypub.actor.key.cached	boolean	Whether the actor's public keys are cached.	true
activitypub.actor.type	string[]	The qualified URI(s) of the actor type(s).	["https://www.w3.org/ns/activitystreams#Person"]
activitypub.collection.id	string	The URI of the collection object.	"https://example.com/collection/1"
activitypub.collection.type	string[]	The qualified URI(s) of the collection type(s).	["https://www.w3.org/ns/activitystreams#OrderedCollection"]
activitypub.collection.total_items	int	The total number of items in the collection.	42
activitypub.object.id	string	The URI of the object or the object enclosed by the activity.	"https://example.com/object/1"
activitypub.object.type	string[]	The qualified URI(s) of the object type(s).	["https://www.w3.org/ns/activitystreams#Note"]
activitypub.object.in_reply_to	string[]	The URI(s) of the original object to which the object reply.	["https://example.com/object/1"]
activitypub.inboxes	int	The number of inboxes the activity is sent to.	12
activitypub.shared_inbox	boolean	Whether the activity is sent to the shared inbox.	true
fedify.actor.identifier	string	The identifier of the actor.	"1"
fedify.inbox.recipient	string	The identifier of the inbox recipient.	"1"
fedify.object.type	string	The URI of the object type.	"https://www.w3.org/ns/activitystreams#Note"
fedify.object.values.{parameter}	string[]	The argument values of the object dispatcher.	["1", "2"]
fedify.collection.cursor	string	The cursor of the collection.	"eyJpZCI6IjEiLCJ0eXBlIjoiT3JkZXJlZENvbGxlY3Rpb24ifQ=="
fedify.collection.items	number	The number of items in the collection page. It can be less than the total items.	10
http_signatures.signature	string	The signature of the HTTP request in hexadecimal.	"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"
http_signatures.algorithm	string	The algorithm of the HTTP request signature.	"rsa-sha256"
http_signatures.key_id	string	The public key ID of the HTTP request signature.	"https://example.com/actor/1#main-key"
http_signatures.digest.{algorithm}	string	The digest of the HTTP request body in hexadecimal. The {algorithm} is the digest algorithm (e.g., sha, sha-256).	"d41d8cd98f00b204e9800998ecf8427e"
ld_signatures.key_id	string	The public key ID of the Linked Data signature.	"https://example.com/actor/1#main-key"
ld_signatures.signature	string	The signature of the Linked Data in hexadecimal.	"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"
ld_signatures.type	string	The algorithm of the Linked Data signature.	"RsaSignature2017"
object_integrity_proofs.cryptosuite	string	The cryptographic suite of the object integrity proof.	"eddsa-jcs-2022"
object_integrity_proofs.key_id	string	The public key ID of the object integrity proof.	"https://example.com/actor/1#main-key"
object_integrity_proofs.signature	string	The integrity proof of the object in hexadecimal.	"73a74c990beabe6e59cc68f9c6db7811b59cbb22fd12dcffb3565b651540efe9"
webfinger.resource	string	The queried resource URI.	"acct:fedify@hollo.social"
webfinger.resource.scheme	string	The scheme of the queried resource URI.	"acct"