Fedify 1.3.0: OpenTelemetry 지원 및 메시지 큐 개선

Fedify 1.3.0 릴리스를 발표하게 되어 기쁩니다. 이번 버전에서는 관찰 가능성, 메시지 큐 구성, 개발자 경험 측면에서 큰 개선이 이루어졌습니다. 연합형 서버 애플리케이션을 더 쉽게 구축하고 모니터링할 수 있도록 하는 여러 가지 새로운 기능과 개선 사항이 도입되었습니다.

OpenTelemetry 통합

이번 릴리스의 주요 기능은 포괄적인 OpenTelemetry 지원입니다. Fedify는 이제 다양한 작업을 OpenTelemetry 스팬으로 자동 계측하여 애플리케이션의 동작에 대한 자세한 통찰력을 제공합니다. 이 기능을 통해 다음과 같은 것들이 가능해집니다:

• 상세한 타이밍 정보가 포함된 HTTP 요청 및 응답 추적
• 액터 및 컬렉션 디스패칭 모니터링
• 인박스 및 아웃박스 작업 관찰
• 서명 검증 프로세스 분석
• 그 외 다수!

Fedify 애플리케이션에서 OpenTelemetry를 설정하는 것은 간단합니다. OpenTelemetry SDK를 구성하면 Fedify가 자동으로 다양한 작업에 대한 스팬을 생성합니다. 다음은 간단한 예시입니다:

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",
  }),
});

sdk.start();

Sentry의 OpenTelemetry 지원과도 통합할 수 있습니다:

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

const federation = createFederation({
  tracerProvider: getClient()?.traceProvider,
  // ... 기타 옵션
});

참고로 Sentry의 OpenTelemetry 통합은 @sentry/node 8.0.0부터 사용 가능하지만, 2024년 11월 기준으로 @sentry/deno나 @sentry/bun에서는 아직 사용할 수 없습니다.

계측된 스팬과 그 속성의 전체 목록은 OpenTelemetry 문서를 확인해주세요.

메시지 큐 구성 개선

Fedify 1.3.0에서는 수신 및 발신 액티비티에 대해 서로 다른 메시지 큐를 구성할 수 있게 되었습니다. 이 기능은 다양한 유형의 액티비티를 처리하는 데 있어 더 큰 유연성을 제공합니다. 다음과 같은 구성이 가능합니다:

• 수신 및 발신 액티비티에 대해 서로 다른 메시지 큐 사용
• 수신 액티비티에만 메시지 큐 사용
• 발신 액티비티에만 메시지 큐 사용
• 또는 위의 조합

다음은 몇 가지 구성 예시입니다:

수신 및 발신 액티비티에 대해 서로 다른 큐 사용하기:

import { createFederation } from "@fedify/fedify";
import { RedisMessageQueue } from "@fedify/redis";
import { PostgresMessageQueue } from "@fedify/postgres";

const federation = createFederation({
  queue: {
    inbox: new PostgresMessageQueue(postgres("postgresql://...")),
    outbox: new RedisMessageQueue(redis),
  },
  // ... 기타 옵션
});

수신 액티비티에만 메시지 큐 사용하기:

const federation = createFederation({
  queue: {
    inbox: new PostgresMessageQueue(postgres("postgresql://...")),
    // outbox가 제공되지 않음; 발신 액티비티는 큐에 들어가지 않음
  },
  // ... 기타 옵션
});

수동 활동 라우팅

이제 실제 HTTP 요청 없이도 수동으로 액티비티를 인박스 리스너로 라우팅할 수 있습니다. 이는 다른 Activity 안에 포함된 Activity 객체를 처리해야 할 때 특히 유용합니다. 예를 들면:

federation.setInboxListeners("/users/{identifier}/inbox", "/inbox")
  .on(Announce, async (ctx, announce) => {
    const object = await announce.getObject();
    if (object instanceof Activity) {
      // 포함된 액티비티를 해당하는 인박스 리스너로 라우팅
      await ctx.routeActivity(ctx.recipient, object);
    }
  });

자세한 내용은 관련 문서를 참조하세요.

SvelteKit 통합

robin-maki 님(@robin_maki@planet.moe)의 기여 덕분에, Fedify는 이제 새로운 @fedify/fedify/x/sveltekit 모듈을 통해 SvelteKit을 공식적으로 지원합니다. 이 통합을 통해 SvelteKit으로 연합형 애플리케이션을 더 쉽게 구축할 수 있습니다:

import { createFederation } from "@fedify/fedify";
import { fedifyHook } from "@fedify/fedify/x/sveltekit";

const federation = createFederation({
  // ... 구성
});

export const handle = fedifyHook(federation, (req) => "컨텍스트 데이터");

자세한 내용은 관련 문서를 참조하세요.

더 나은 HTTP 요청 식별

Fedify는 이제 생성하는 모든 HTTP 요청에 적절한 User-Agent 헤더를 포함합니다. 이를 통해 서버 로그에서 Fedify가 생성한 요청을 더 쉽게 식별하고 추적할 수 있습니다. 기본 형식은 다음과 같습니다:

Fedify/1.3.0 (Deno/2.1.2)

사용자 정의 user agent 문자열이나 옵션을 제공하여 이를 커스터마이즈할 수 있습니다:

createFederation({
  userAgent: {
    software: "MyApp/1.0.0",
    url: "https://myinstance.com/"
  },
  // ... 기타 옵션
});

기타 개선 사항

• Context.sendActivity()와 InboxContext.forwardActivity() 메서드가 이제 작업을 큐에 넣지 못했을 때 적절하게 거부합니다
• 다양한 버그 수정 및 성능 개선
• 문서 및 예제 개선

1.3.0으로 업그레이드하기

Fedify 1.3.0은 JSR과 npm 모두에서 사용할 수 있습니다. 업그레이드하려면:

JSR(Deno)의 경우:

deno add jsr:@fedify/fedify@1.3.0

npm(Node.js와 Bun)의 경우:

npm  add @fedify/fedify@1.3.0
pnpm add @fedify/fedify@1.3.0
yarn add @fedify/fedify@1.3.0
bun  add @fedify/fedify@1.3.0 

앞으로의 전망

우리는 이러한 새로운 기능과 개선 사항들에 대해 매우 기대하고 있으며, 이를 통해 Fedify로 연합형 애플리케이션을 구축하는 것이 더욱 즐거워질 것이라고 믿습니다. 계속해서 업데이트를 지켜봐 주시고, 질문이나 피드백이 있으시다면 Matrix 채팅(영어)이나 Discord 서버(한국어)에 주저하지 말고 참여해 주세요!

전체 변경 사항 목록은 변경 로그를 확인해 주세요.