Unverified Commit 3f2cb6c8 authored by Hong Minhee's avatar Hong Minhee
Browse files

Docs for OpenTelemetry 

[ci skip]
parent 113cabf2

docs/.vitepress/config.mts

+1 −0
Original line number Diff line number Diff line
@@ -70,6 +70,7 @@ const MANUAL = { 
    { text: "Integration", link: "/manual/integration.md" },

    { text: "Testing", link: "/manual/test.md" },

    { text: "Logging", link: "/manual/log.md" },

    { text: "OpenTelemetry", link: "/manual/opentelemetry.md" },

  ],

  activeMatch: "/manual",

};

docs/manual/federation.md

+12 −0
Original line number Diff line number Diff line
@@ -340,6 +340,18 @@ same path. 


Turned off by default.



### `tracerProvider`



*This API is available since Fedify 1.3.0.*



The OpenTelemetry tracer provider that the `Federation` object uses to

instrument various parts of Fedify for tracing.  If omitted, it is configured

to use the default tracer provider (i.e., [`trace.getTracerProvider()`]).



For more information, see the [*OpenTelemetry* section](./opentelemetry.md).



[`trace.getTracerProvider()`]: https://open-telemetry.github.io/opentelemetry-js/classes/_opentelemetry_api.TraceAPI.html#getTracerProvider





The `~Federation.fetch()` API

-----------------------------

docs/manual/opentelemetry.md

0 → 100644
+147 −0
Original line number Diff line number Diff line 
---

description: >-

  OpenTelemetry is a 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.

---



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.



[OpenTelemetry]: https://opentelemetry.io/





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:



::: code-group



~~~~ sh [Deno]

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

~~~~



~~~~ sh [Node.js]

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

~~~~



~~~~ sh [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:



~~~~ typescript twoslash

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`](./federation.md#tracerprovider) option to explicitly

configure the [`TracerProvider`] for 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:



~~~~ typescript twoslash

// @noErrors: 2339

import type { KvStore } from "@fedify/fedify";

// ---cut-before---

import { createFederation } from "@fedify/fedify";

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



const federation = createFederation<void>({

// ---cut-start---

  kv: null as unknown as KvStore,

// ---cut-end---

  // 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.



[`TracerProvider`]: https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.TracerProvider.html

[Sentry]: https://sentry.io/

[@sentry/node]: https://npmjs.com/package/@sentry/node

[@sentry/deno]: https://npmjs.com/package/@sentry/deno

[@sentry/bun]: https://npmjs.com/package/@sentry/bun

[*OpenTelemetry Support* section]: https://docs.sentry.io/platforms/javascript/guides/node/opentelemetry/





Instrumented spans

------------------



Fedify automatically instruments the following operations with OpenTelemetry

spans:



| Operation            | Description                       |

|----------------------|-----------------------------------|

| `Federation.fetch()` | Serves the incoming HTTP request. |



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 IRI of the activity object.                                                 | `"https://example.com/activity/1"`                 |

| `activitypub.activity.type`         | string[] | The qualified IRI(s) of the activity type(s).                                   | `["https://www.w3.org/ns/activitystreams#Create"]` |

| `activitypub.activity.to`           | string[] | The IRI(s) of the recipient collections/actors of the activity.                 | `["https://example.com/1/followers/2"]`            |

| `activitypub.activity.cc`           | string[] | The IRI(s) of the carbon-copied recipient collections/actors of the activity.   | `["https://www.w3.org/ns/activitystreams#Public"]` |

| `activitypub.activity.resend_count` | int      | The ordinal number of activity resending attempt (if and only if it's retried). | `3`                                                |

| `activitypub.actor.id`              | string   | The IRI of the actor object.                                                    | `"https://example.com/actor/1"`                    |

| `activitypub.actor.type`            | string[] | The qualified IRI(s) of the actor type(s).                                      | `["https://www.w3.org/ns/activitystreams#Person"]` |

| `activitypub.object.id`             | string   | The IRI of the object or the object enclosed by the activity.                   | `"https://example.com/object/1"`                   |

| `activitypub.object.type`           | string[] | The qualified IRI(s) of the object type(s).                                     | `["https://www.w3.org/ns/activitystreams#Note"]`   |

| `activitypub.object.in_reply_to`    | string[] | The IRI(s) of the original object to which the object reply.                    | `["https://example.com/object/1"]`                 |

| `webfinger.resource`                | string   | The queried resource URI.                                                       | `"acct:fedify@hollo.social"`                       |



[OpenTelemetry Semantic Conventions]: https://opentelemetry.io/docs/specs/semconv/

docs/package.json

+7 −2
Original line number Diff line number Diff line
@@ -3,7 +3,7 @@ 
    "@braintree/sanitize-url": "^7.1.0",

    "@deno/kv": "^0.8.2",

    "@fedify/amqp": "0.1.0-dev.8",

    "@fedify/fedify": "1.3.0-dev.508",

    "@fedify/fedify": "1.3.0-dev.557",

    "@fedify/postgres": "0.2.2",

    "@fedify/redis": "0.2.0-dev.10",

    "@hono/node-server": "^1.12.2",
@@ -34,5 +34,10 @@ 
    "build": "vitepress build",

    "preview": "vitepress preview"

  },

  "packageManager": "pnpm@9.5.0+sha512.140036830124618d624a2187b50d04289d5a087f326c9edfc0ccd733d76c4f52c3a313d4fc148794a2a9d81553016004e6742e8cf850670268a7387fc220c903"

  "packageManager": "pnpm@9.5.0+sha512.140036830124618d624a2187b50d04289d5a087f326c9edfc0ccd733d76c4f52c3a313d4fc148794a2a9d81553016004e6742e8cf850670268a7387fc220c903",

  "dependencies": {

    "@opentelemetry/exporter-trace-otlp-proto": "^0.55.0",

    "@opentelemetry/sdk-node": "^0.55.0",

    "@sentry/node": "^8.40.0"

  }

}

docs/pnpm-lock.yaml

+1325 −8

File changed.

Preview size limit exceeded, changes collapsed.