개요

Apps를 사용하면 표준 개발 워크플로에 따라 React 및 TypeScript(또는 JavaScript)로 애플리케이션을 로컬에서 코드로 빌드할 수 있습니다.

Datadog Apps는 App Builder 앱과 동일한 권한 모델을 사용합니다. 또한 대시보드 및 Internal Developer Portal과 같은 다른 Datadog 제품에 포함할 수도 있습니다.

다음이 필요할 때 Datadog Apps를 선택합니다.

• 팀 협업: 여러 엔지니어가 동일한 앱에 기여하며 기존 소스 제어를 통해 코드 검토 및 버전 기록을 관리합니다.
• 소스 제어 및 CI/CD: GitHub에 앱을 저장하고 병합 시 자동으로 배포합니다.
• AI 지원 개발: 선호하는 로컬 도구(Cursor, GitHub Copilot, Claude 등)를 사용하여 코드를 생성하고 개선합니다.
• 사용자 지정 클라우드 공급자 및 API: 자체 백엔드 코드를 사용하여 Action Catalog를 벗어난 서비스와 통합합니다.
• 복잡한 UI 및 로직: 컴포넌트, 상태, 렌더링에 대해 React 및 TypeScript를 완전하게 제어합니다.

전제 조건

• Node.js 버전 20.12.0 이상. 버전 검사:

  node --version
  

• 선택 사항: Datadog API 키 및 액션 API 액세스가 활성화된 애플리케이션 키. API 키 기반 빌드 텔레메트리(빌드 메트릭 및 Error Tracking 소스맵 업로드)과 CI/CD 업로드에 필요합니다. 지침은 API 및 애플리케이션 키를 참조하세요.

  애플리케이션 키에서 액션 API 액세스를 활성화하려면 다음 작업을 수행합니다.

  1. Organization Settings > Application Keys]7로 이동합니다.
  2. 애플리케이션 키를 선택합니다.
  3. Actions API Access****를 활성화합니다.

앱 스캐폴딩

1. 스캐폴딩 명령을 실행하여 앱을 생성합니다.

   npm create @datadog/apps@latest
   

2. 대화형 프롬프트를 따라 앱 이름과 템플릿을 구성합니다.

생성된 앱 구조

스캐폴딩된 프로젝트에는 다음 항목이 포함됩니다.

datadog-app 스킬 사용

datadog-app 에이전트 스킬은 AI 코딩 에이전트에게 스캐폴딩, 로컬 개발, 업로드, 게시, CI/CD, 문제 해결, DDSQL 및 Action Catalog 사용을 포함한 Datadog Apps 워크플로에 대한 지침을 제공합니다. 이 스킬은 agent-skills GitHub 리포지토리에서 사용할 수 있습니다.

설치

npx skills add datadog-labs/agent-skills \
  --skill datadog-app \
  --full-depth -y

skills CLI는 Claude Code, Codex, Cursor, Gemini CLI, OpenCode 및 기타 코딩 에이전트를 지원합니다. 특정 에이전트를 대상으로 지정하려면 스킬 CLI 문서를 참조하세요. 설치 후에도 스킬이 나타나지 않으면 코딩 에이전트를 다시 시작하세요.

프롬프트 예시

• Scaffold a Datadog App called my-app.
• Run this Datadog App locally.
• Upload and publish this Datadog App.
• Set up CI/CD for this Datadog App.
• Troubleshoot this Datadog App authentication error.
• Add a table component to this Datadog App using DRUIDS.

로컬에서 앱 개발

1. 개발 서버를 시작합니다.

   npm run dev
   

2. 터미널에 표시된 URL(예: http://localhost:5173/)을 열면 앱을 미리 확인할 수 있습니다.

백엔드 함수를 로컬에서 실행할 때와 같이 개발 서버가 Datadog을 호출해야 하는 경우 기본적으로 OAuth를 사용합니다. 권한 부여가 필요한 경우 이 명령이 브라우저 프롬프트를 엽니다. 권한 부여가 완료되면 토큰이 운영 체제 자격 증명 저장소에 캐시됩니다.

DD_API_KEY 및 DD_APP_KEY를 둘 다 설정하면 생성된 앱은 OAuth 대신 해당 키를 사용합니다.

백엔드 함수

*.backend.ts 또는 *.backend.js와 일치하는 파일에는 백엔드 함수가 포함되어 있습니다. 백엔드 함수는 서버 측에서 실행되며 연결에 액세스할 수 있습니다. 프런트엔드는 표준 ES 모듈처럼 백엔드 함수를 가져와 호출합니다.

백엔드 함수는 @datadog/action-catalog 라이브러리를 통해 Datadog의 Action Catalog에 있는 모든 작업을 호출할 수 있습니다. Action Catalog는 클라우드 제공업체, SaaS 도구 및 Datadog API와 상호 작용하기 위해 재사용 가능한 사전 구축 작업을 제공합니다. 처음부터 API 클라이언트를 작성하는 대신 기존 통합을 기반으로 빌드할 수 있습니다.

이 라이브러리는 AWS, Azure, GCP, Datadog API, GitHub, GitLab, Slack, Jira, PagerDuty, ServiceNow, OpenAI, Anthropic 및 범용 HTTP를 포함한 통합을 래핑하는 완전한 유형의 TypeScript 클라이언트입니다. @datadog/action-catalog에서 작업을 가져오면 각 작업에 대해 유형이 지정된 입력 및 응답을 얻을 수 있습니다.

@datadog/apps-backend 패키지를 통해 백엔드 유틸리티를 조회할 수 있습니다. 유틸리티를 사용하여 호출하는 사용자의 정보 검색과 같은 일반적인 작업을 수행할 수 있습니다.

import { getInitiatingUser, type User } from '@datadog/apps-backend/user';

export async function getCurrentUser(): Promise<User> {
 return getInitiatingUser();
}

import { listHosts, type ListHostsResponse } from '@datadog/action-catalog/dd/hosts';

export async function getHosts(filter?: string): Promise<ListHostsResponse> {
    const response = await listHosts({
        inputs: {
            filter: filter ?? '*',
            count: 10,
            include_hosts_metadata: true,
        },
    });
    return response;
}

import { useState, useEffect } from 'react';
import { getHosts } from './listHosts.backend';

function App() {
    const [hostCount, setHostCount] = useState<number>(0);

    useEffect(() => {
        getHosts().then((response) => {
            setHostCount(response.host_list?.length ?? 0);
        });
    }, []);

    return (
        <div style={{ padding: '2rem', textAlign: 'center' }}>
            <h1>Welcome to my-app</h1>
            <p>Monitoring {hostCount} hosts</p>
        </div>
    );
}

export default App;

UI 구성 요소

@datadog/druids을 사용하여 테이블, 버튼, 차트, 양식 등 Datadog 제품 전반에서 사용되는 것과 동일한 React 구성 요소로 앱의 UI를 빌드합니다. DRUIDS를 사용하여 빌드하면 앱이 Datadog의 다른 부분과 동일한 모양 및 느낌을 유지할 수 있습니다.

라이브러리 설치:

npm install @datadog/druids

일반 React 구성 요소를 가져오는 것과 동일한 방식으로 구성 요소를 가져옵니다.

import { Button } from '@datadog/druids';

DRUIDS는 피어 종속성으로 React 18 또는 19가 필요합니다. 사용 가능한 구성 요소 세트는 npm의 패키지를 참조하세요.

앱 빌드 및 업로드

npm run build를 사용하여 업로드하지 않고 로컬에서 앱을 빌드할 수 있습니다. 이는 일반적으로 모든 빌드를 업로드할 필요가 없는 로컬 개발에 권장되는 기본 설정입니다.

npm run upload를 사용하여 앱을 빌드하고 Datadog에 업로드합니다. 이 명령은 DD_APPS_UPLOAD_ASSETS=1인 상태로 vite build를 실행합니다.

npm run upload

업로드는 기본적으로 OAuth를 사용하며 처음 실행 시 브라우저 인증 흐름이 열릴 수 있습니다. DD_API_KEY 및 DD_APP_KEY를 모두 설정하면 업로드 시 API 및 애플리케이션 키 인증이 대신 사용됩니다.

사용 가능한 환경 변수는 다음과 같습니다:

프로덕션 배포의 경우 GitHub Actions로 CI/CD 설정DataDog/apps-github-action이 업로드 단계를 자동으로 처리합니다.

업로드에 성공하면 빌드 출력에 Datadog에서 앱에 액세스할 수 있는 URL이 표시됩니다.

앱 게시 및 관리

앱을 업로드하면 앱 목록에 나타납니다. 앱 목록에서 다음을 수행할 수 있습니다：

• 앱 게시
• 앱 이름 및 설명 편집
• 권한 관리
• 대시보드, 노트북 및 Internal Developer Portal에서 앱 임베드

딥 링크로 임베드된 앱 상태 공유

앱이 임베드되면 해당 URL 상태가 호스트 페이지의 URL에 미러링됩니다. 여기에는 경로, 탭, 해시 값 및 쿼리 매개변수가 포함됩니다. 해당 호스트 URL을 복사하여 공유하면 동일한 앱 내 상태로 앱이 열립니다.

딥 링크는 DatadogAppProvider 래퍼에서 자동으로 지원됩니다. 앱에서 딥 링크가 작동하지 않으면 @datadog/apps-frontend을(를) 설치하고 DatadogAppProvider에서 main.tsx으로 앱을 감싸십시오:

npm install @datadog/apps-frontend@latest

import { DatadogAppProvider } from '@datadog/apps-frontend/embedding/react';

function App() {
  return (
    <DatadogAppProvider>
      {/* your app */}
    </DatadogAppProvider>
  );
}

다른 코드는 변경할 필요가 없습니다. 앱 내의 모든 history.pushState, history.replaceState 또는 해시 탐색은 호스트 페이지의 URL에 자동으로 미러링됩니다.

딥 링크를 끄려면 disabledModules에 datadog.deep-links 모듈을 전달하십시오:

<DatadogAppProvider disabledModules={['datadog.deep-links']}>
  {/* your app */}
</DatadogAppProvider>

GitHub Actions로 CI/CD 설정

main 브랜치에 푸시할 때마다 앱을 자동으로 업로드하려면 DataDog/apps-github-action GitHub Action을 사용합니다. 이 작업은 앱을 빌드하고 Datadog에 업로드합니다.

CI/CD 업로드에는 API 및 애플리케이션 키 인증이 필요합니다. 액션 API 액세스가 활성화된 Datadog API 키와 애플리케이션 키를 만들고 GitHub 비밀로 저장합니다.

조직이 US1(datadoghq.com)에 없으면 vite.config.ts의 auth.site를 Datadog 사이트로 설정합니다. 빌드는 앱을 업로드할 때 이 구성을 읽으므로 동일한 설정이 로컬 개발에도 적용됩니다. Datadog 사이트는 .

datadogVitePlugin({
  auth: {
    site: '<YOUR_DATADOG_SITE>',
  },
});

앱의 리포지토리에 .github/workflows/cd.yml을 생성합니다.

name: Continuous Deployment
on:
  push:
    branches:
      - main

permissions:
  contents: read

jobs:
  deploy-app:
    name: Deploy Datadog App
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write

    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Setup Node.js
        uses: actions/setup-node@v6

      - name: Deploy
        uses: DataDog/apps-github-action@v0.0.2
        with:
          datadog-api-key: ${{ secrets.DATADOG_API_KEY }}
          datadog-app-key: ${{ secrets.DATADOG_APP_KEY }}
          app-directory: .

문제 해결

인증 오류

로컬 개발 및 업로드 시 OAuth 인증 오류는 다음 원인 중 하나로 인해 발생할 수 있습니다.

• OAuth 브라우저 흐름이 완료되지 않았습니다.
• 캐시된 OAuth 토큰이 유효하지 않습니다.
• auth.site 가 Datadog 사이트와 일치하지 않습니다.

명령을 다시 실행하고 브라우저 승인 흐름을 완료합니다.

API 및 애플리케이션 키 인증을 사용하는 경우 인증 오류는 일반적으로 자격 증명이 누락되었거나 유효하지 않음을 나타냅니다. 백엔드 함수 호출 실패도 원인이 같을 수 있습니다. DD_API_KEY 및 DD_APP_KEY가 설정되어 있는지, 그리고 애플리케이션 키에 액션 API 액세스가 활성화되어 있는지 확인합니다.

빌드는 성공하지만 아무것도 업로드되지 않습니다.

npm run upload를 실행했는지(npm run build가) 아님) 확인하고 vite.config.ts의 dryRun이 true로 설정되어 있지 않은지 확인합니다.

스캐폴딩 중 Node.js 버전 오류

스캐폴딩 도구에는 Node.js 20.12.0 이상이 필요합니다. 지원되는 버전에서도 오류가 발생하면 v22로 업그레이드하세요. nvm, Volta 또는 fnm과 같은 버전 관리자를 사용하거나 Node.js 웹사이트에서 다운로드하세요.

추가 자료

추가적인 유용한 설명서, 링크 및 기사:

Datadog Apps를 사용하여 AI Agent에서 내부 애플리케이션 배포블로그 Datadog Apps 데모비디오 App Builder설명서 App Builder 앱 임베드설명서 액세스 및 인증설명서