관측 가능성

원문 보기 위키 갱신 2026.10.07

관측 가능성 (Observability)

레거시 문서

출처: 문서

본문

레거시 문서

이 섹션은 레거시 플러그인 문서의 일부예요. 새 백엔드 시스템 로깅은 Logger와 Root Logger 코어 서비스 문서를 참고하세요. 헬스 체크는 Root Health를 참고하세요.

이 문서는 Backstage 통합자에게 제공되는 관측 가능성 옵션을 간략히 설명해요.

Datadog RUM 이벤트

앱에 Datadog Events를 설치하는 방법을 여기에서 확인하세요.

로깅

새 백엔드

백엔드는 중앙 로깅 서비스인 rootLogger와, coreServices의 플러그인 기반 로거 logger를 제공해요. 로그에 추가 세분성을 더하려면 플러그인 기반 로거에서 .child() 메서드를 사용해 자식 로거를 만들고 JSON 데이터를 제공할 수 있어요. 예를 들어 플러그인의 특정 스팬에 대한 항목을 로그하고 싶다면 이렇게 할 수 있어요.

export function createRouter({ logger }) {  const router = Router();  router.post('/task/:taskId/queue', (req, res) => {    const { taskId } = req.params;    const taskLogger = logger.child({ task: taskId });    taskLogger.log('Queueing this task.');  });  router.get('/task/:taskId/results', (req, res) => {    const { taskId } = req.params;    const taskLogger = logger.child({ task: taskId });    taskLogger.log('Getting the results of this task.');  });}

rootLogger 구현을 오버라이드해 Backstage 인스턴스의 모든 로그에 추가 메타데이터를 추가할 수도 있어요. rootLogger 문서에서 예시를 볼 수 있어요.

이전 백엔드

백엔드는 플러그인이 로깅 요구에 사용하도록 기대되는 중앙 winston 루트 로거를 제공해요. 기본 프로덕션 설정에서는 stdout에 구조화된 JSON 로그를 내보내며, "service": "backstage" 필드가 있고 플러그인별로 태그가 지정돼요. 로그 메시지를 내보낸 프로세스의 어느 부분인지 더 세밀하게 지정하려는 플러그인은 이를 위해 "component" 필드를 추가해야 해요.

예시 로그 줄은 다음과 같이 보일 수 있어요.

{  "service": "backstage",  "type": "plugin",  "plugin": "catalog",  "component": "catalog-all-locations-refresh",  "level": "info",  "message": "Locations Refresh: Refreshing location bootstrap:bootstrap"}

헬스 체크

새 백엔드 (1.29.0 이후)

새 백엔드는 전체 백엔드 인스턴스에 대한 헬스 체크를 제공하기 위해 /.backstage/health/v1/readiness와 /.backstage/health/v1/liveness 엔드포인트를 구현하는 RootHealthService를 제공해요.

이 새 서비스와 커스터마이즈 방법에 대한 더 자세한 내용은 Root Health Service 문서에서 읽을 수 있어요.

새 백엔드 (1.29.0 이전)

새 백엔드는 헬스 체크가 플러그인 기반이 되는 방향으로 나아가고 있어서, 현재 헬스 체크 라우트를 제공하는 플러그인이 없어요. 그러나 직접 쉽게 추가할 수 있어요.

import {  coreServices,  createBackendModule,  createBackendPlugin,} from '@backstage/backend-plugin-api';const healthCheck = createBackendPlugin({  pluginId: 'healthcheck',  register(env) {    env.registerInit({      deps: {        rootHttpRouter: coreServices.rootHttpRouter,      },      init: async ({ rootHttpRouter }) => {        // You can adjust the route name and response as you need.        rootHttpRouter.use('/healthcheck', (req, res) => {          res.json({ status: 'ok' });        });      },    });  },});

이전 백엔드

Backstage 저장소의 예시 이전 백엔드는 /healthcheck 라우트에 아주 기본적인 헬스 체크 엔드포인트를 제공해요. 백엔드에 그러한 핸들러를 추가하고, 특정 헬스 체크 요구에 맞는 자체 로직을 제공할 수도 있어요.

관측 가능성