Processors
Notifications는 NotificationProcessor로 확장할 수 있어요. 이 프로세서들을 사용하면 알림이 보내지기 전에 꾸미거나(데코레이션) 알림을 외부 서비스로 보낼 수 있어요.
출처: 문서
본문
Notifications는 NotificationProcessor로 확장할 수 있어요. 이 프로세서들을 사용하면 알림이 보내지기 전에 꾸미거나(데코레이션) 알림을 외부 서비스로 보낼 수 있어요.
필요에 따라 프로세서는 알림의 내용을 수정하거나 이메일, Slack, 기타 서비스 같은 다른 시스템으로 라우팅할 수 있어요.
프로세서 작성의 좋은 예시는 Email Processor예요.
먼저 알림 프로세서를 만들어 보세요.
import { Notification } from '@backstage/plugin-notifications-common';import { NotificationProcessor } from '@backstage/plugin-notifications-node';class MyNotificationProcessor implements NotificationProcessor { // preProcess is called before the notification is saved to database. // This is a good place to modify the notification before it is saved and sent to the user. async preProcess(notification: Notification): Promise<Notification> { if (notification.origin === 'plugin-my-plugin') { notification.payload.icon = 'my-icon'; } return notification; } // postProcess is called after the notification is saved to database and the signal is emitted. // This is a good place to send the notification to external services. async postProcess(notification: Notification): Promise<void> { nodemailer.sendEmail({ from: 'backstage', to: 'user', subject: notification.payload.title, text: notification.payload.description, }); }}
두 처리 함수 모두 선택 사항이며, 그중 하나만 구현해도 돼요.
알림 시스템에 알림 프로세서를 추가하려면:
import { notificationsProcessingExtensionPoint } from '@backstage/plugin-notifications-node';import { Notification } from '@backstage/plugin-notifications-common';export const myPlugin = createBackendPlugin({ pluginId: 'myPlugin', register(env) { env.registerInit({ deps: { notifications: notificationsProcessingExtensionPoint, // ... }, async init({ notifications }) { // ... notifications.addProcessor(new MyNotificationProcessor()); }, }); },});
내장 프로세서
Backstage에는 즉시 사용할 수 있는 몇 가지 프로세서가 함께 제공돼요.
Email Processor
Email 프로세서는 이메일로 사용자에게 알림을 보내는 데 사용돼요. 이메일 프로세서를 설치하려면 @backstage/plugin-notifications-backend-module-email 패키지를 백엔드에 추가하세요.
yarn workspace backend add @backstage/plugin-notifications-backend-module-email
이메일 프로세서를 백엔드에 추가하세요.
import { createBackend } from '@backstage/plugin-notifications-backend';const backend = createBackend();// ...backend.add(import('@backstage/plugin-notifications-backend-module-email'));
이메일 프로세서를 구성하려면 app-config.yaml에 다음 구성을 추가해야 해요.
notifications: email: smtp: host: smtp.example.com port: 587 secure: false username: ${SMTP_USERNAME} password: ${SMTP_PASSWORD}
STMP 외에도 이메일 프로세서는 다음 전송 방식을 지원해요.
-
SES
-
sendmail
-
stream(디버깅 목적으로만)
더 자세한 내용은 https://github.com/backstage/backstage/blob/master/plugins/notifications-backend-module-email/README.md 에서 확인할 수 있어요.
Slack Processor
Slack 프로세서는 Slack의 사용자와 채널에게 알림을 보내는 데 사용돼요.
Slack 구성
이를 사용하려면 Slack App을 만들거나 기존 앱을 사용해야 해요. 최소한 다음 스코프가 있어야 해요:
chat:write, users:read, im:write(다이렉트 메시지 지원용).
추가로 앱이 멤버가 아닌 공개 채널에 메시지를 보내려면 chat:write.public 스코프를 포함할 수 있어요.
이런 스코프는 OAuth & Permissions 아래에 있어요. 또한 Bot User OAuth Token을 저장해 두고 싶을 거예요. 이는 다음 단계에서 app-config.yaml을 구성하는 데 필요할 거예요.
Backstage 구성
Slack 프로세서를 설치하려면 @backstage/plugin-notifications-backend-module-slack 패키지를 백엔드에 추가하세요.
yarn workspace backend add @backstage/plugin-notifications-backend-module-slack
Slack 프로세서를 백엔드에 추가하세요.
// packages/backend/src/index.tsimport { createBackend } from '@backstage/plugin-notifications-backend';const backend = createBackend();// ...backend.add(import('@backstage/plugin-notifications-backend-module-slack'));
Slack App에서 얻은 토큰을 사용해 app-config.yaml에서 Slack 모듈을 구성하세요.
notifications: processors: slack: - token: xoxb-XXXXXXXXX broadcastChannels: # Optional, if you wish to support broadcast notifications. - C12345678 username: 'Backstage Bot' # Optional, defaults to the name of the Slack App. concurrencyLimit: 20 # Optional, number of messages allowed per interval. Defaults to 10. throttleInterval: 1m # Optional, Accepts ISO-8601 duration, ms-style ("1m", "30s"), or HumanDuration ({ minutes: 2 }). Defaults to 1 minute
slack 배열에 여러 인스턴스를 추가할 수 있어서, 두 개 이상의 Slack 워크스페이스에 메시지를 보내야 한다면 여러 구성을 가질 수 있어요. Org-Wide App 설치는 현재 지원되지 않아요.
Slack 메시지 구조 커스터마이즈
notificationsSlackBlockKitExtensionPoint를 통해 자체 메시지 레이아웃을 제공해 Slack에서 알림이 어떻게 보이는지 커스터마이즈할 수 있어요.
import { createBackendModule } from '@backstage/backend-plugin-api';import { notificationsSlackBlockKitExtensionPoint } from '@backstage/plugin-notifications-backend-module-slack';export const notificationsSlackFormattingModule = createBackendModule({ pluginId: 'notifications', moduleId: 'slack-formatting', register(reg) { reg.registerInit({ deps: { slackBlockKit: notificationsSlackBlockKitExtensionPoint, }, async init({ slackBlockKit }) { slackBlockKit.setBlockKitRenderer(payload => [ // Custom block kit layout ]); }, }); },});
커스텀 렌더러를 등록하지 않으면 기본 렌더러가 사용돼요.
브로드캐스트 채널 라우팅
브로드캐스트 알림이 어디로 보내질지 더 세밀하게 제어하려면 broadcastRoutes를 사용해 오리진 및/또는 토픽에 따라 알림을 다른 Slack 채널로 라우팅할 수 있어요. 서로 다른 유형의 알림을 다른 채널로 보내고 싶을 때 유용해요.
notifications: processors: slack: - token: xoxb-XXXXXXXXX # Legacy option - used as fallback when no routes match broadcastChannels: - general-notifications # Route broadcasts based on origin and/or topic broadcastRoutes: # Most specific: matches both origin AND topic - origin: plugin:catalog topic: alerts channel: catalog-alerts # Origin only: all notifications from this origin - origin: plugin:catalog channel: catalog-updates # Topic only: all notifications with this topic (any origin) - topic: security channel: security-team # Multiple channels: send to several channels at once - origin: external:monitoring channel: - ops-team - on-call-alerts
라우트 매칭 우선순위
라우트는 다음 우선순위 순서로 평가돼요.
-
Origin + Topic 매칭(가장 구체적) -
origin과topic을 모두 지정한 라우트가 먼저 매칭돼요. -
Origin-only 매칭 -
origin만 지정한 라우트(topic없음) -
Topic-only 매칭 -
topic만 지정한 라우트(origin없음) -
기본 폴백 - 매칭되는 라우트가 없으면
broadcastChannels로 폴백해요.
가장 먼저 매칭되는 라우트가 이겨요. 매칭되는 라우트가 없고 broadcastChannels도 구성되어 있지 않으면, 브로드캐스트 알림은 Slack으로 보내지지 않아요.
구성 옵션
| | Property | Type | Description | origin | string | Optional. The notification origin to match (e.g., plugin:catalog, external:my-service) | topic | string | Optional. The notification topic to match (e.g., alerts, updates, security) | channel | string or string[] | Required. The Slack channel(s) to send to. Can be channel IDs, channel names, or user IDs
엔티티 요구 사항
엔티티에는 다음 애너테이션이 주석으로 달려 있어야 해요.
slack.com/bot-notify
값은 chat.postMessage가 지원하는 어떤 Slack ID든 될 수 있어요. 예: 사용자(U12345678), 채널(C12345678), 그룹, 또는 다이렉트 메시지 채팅.
사용자의 이메일 주소나 채널 이름을 사용할 수도 있지만, Slack은 ID를 권장해요. 비공개 채널/채팅은 ID를 사용해야 해요.
관측 가능성
OpenTelemetry로 메트릭을 내보내고 있다면 프로세서는 다음 카운터 메트릭을 포함해요.
-
notifications.processors.slack.sent.count- 보낸 메시지 수 -
notifications.processors.slack.error.count- 보내기 실패한 메시지 수