# 팀 수준의 Copilot 사용 지표

일일 사용자 팀 보고서를 일일 사용자별 사용 메트릭 보고서와 조인하여 팀 수준 GitHub Copilot 사용 메트릭을 생성합니다.

사용 메트릭 API는 Copilot 미리 집계된 단일 팀 보고서를 게시하지 않습니다. 팀 수준 메트릭은 **사용자별** 사용 메트릭 보고서(해당 날짜에 대한 각 사용자의 활동이 포함됨)와 **사용자 팀** 보고서(지정된 날짜의 각 사용자 Copilot 팀 멤버 자격을 나열)에 조인하여 생성됩니다. 조인된 행을 집계하여 `team_id` 팀 수준 메트릭을 생성합니다.

동일한 조인 레시피는 필요한 모든 팀 수준의 세분화에 적용할 수 있습니다. 예를 들어 `(team, day)` 기준, `(team, day, language)` 기준, `(team, day, IDE)` 기준, 롤링 윈도우 기준 등이 있습니다.

> \[!NOTE]
> 팀 수준 채택에 대한 UI 기반 보기만 필요한 경우 영향 대시보드의 사용자 팀 매핑은 이 문서에 설명된 조인을 빌드할 필요 없이 기본적으로 팀 수준 채택 코호트 데이터를 표시합니다.
> [Copilot 영향 대시보드 보기](/ko/copilot/how-tos/administer-copilot/view-impact-dashboard)을(를) 참조하세요. 사용자 지정 BI 보고 또는 채택 코호트 이외의 팀 수준 메트릭과 같은 팀별 원시 NDJSON 데이터가 필요한 경우 아래에 설명된 수동 조인을 사용합니다.

## 보고서 가져오기

이 가이드에서 참조하는 두 보고서는 두 단계로 다운로드됩니다. 먼저 원하는 날짜에 대한 REST 엔드포인트를 호출합니다. 엔드포인트는 보고서 파일을 다운로드할 수 있는 시간 제한 서명된 URL을 반환합니다. 그런 다음, 해당 URL이 가리키는 줄 바꿈으로 구분된 JSON(NDJSON) 파일을 다운로드합니다. 사용자 팀 및 사용자별 행은 해당 NDJSON 파일에 있습니다. REST 엔드포인트에서 인라인으로 반환되지 않습니다.

| Report             | 엔드포인트                                                                                   |
| :----------------- | :-------------------------------------------------------------------------------------- |
| 조직의 사용자 팀          | `GET /orgs/{org}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD`               |
| 엔터프라이즈 사용자 팀       | `GET /enterprises/{enterprise}/copilot/metrics/reports/user-teams-1-day?day=YYYY-MM-DD` |
| 조직의 사용자별 사용 지표     | `GET /orgs/{org}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD`                    |
| 엔터프라이즈 사용자별 사용 메트릭 | `GET /enterprises/{enterprise}/copilot/metrics/reports/users-1-day?day=YYYY-MM-DD`      |

각 엔드포인트는 양식의 응답을 반환합니다.

```json
{
  "download_links": [
    "https://example.com/copilot-user-teams-report-1.ndjson"
  ],
  "report_day": "2026-05-07"
}
```

링크의 만료 기간 내의 각 URL에서 파일을 다운로드하여 해당 보고서의 행을 검색합니다.

전체 요청 및 응답 스키마, 인증 요구 사항 및 관련 엔드포인트는 [Copilot 사용 메트릭에 대한 REST API 엔드포인트](/ko/rest/copilot/copilot-usage-metrics)을 참조하세요. 개별 사용 메트릭 필드가 정의되는 방법에 대한 개요는 [Copilot 사용 메트릭에서 사용할 수 있는 데이터](/ko/copilot/reference/copilot-usage-metrics/copilot-usage-metrics)을 참조하세요.

여러 날 창의 경우 매일 엔드포인트를 하루에 한 번 호출하고 일일 결과를 집계합니다. 아래의 [롤링 윈도우 팀 보고서 만들기](#building-rolling-window-team-reports)를 참조하세요.

## 관련된 보고서

팀 수준 메트릭은 팀 멤버 자격에 대한 사용자 팀 보고서와 활동에 대한 사용자별 사용 메트릭 보고서라는 두 개의 보고서 패밀리를 조인하는 데 사용됩니다.

### 사용자 팀 보고서

이러한 보고서는 지정된 날짜에 각 사용자의 팀 멤버 자격을 나열합니다.

| Report                                                             | Scope                                            | 주요 필드 |
| :----------------------------------------------------------------- | :----------------------------------------------- | :---- |
| `organization_user_teams_1_day`                                    | 오늘의 조직 팀 멤버 자격. 조직 팀만 포함합니다.                     |       |
| `user_id`, `user_login`, `day`, `organization_id`, `team_id``slug` |                                                  |       |
| `enterprise_user_teams_1_day`                                      | 하루 동안의 엔터프라이즈 팀 멤버십. 엔터프라이즈 팀과 비즈니스 팀을 모두 포함합니다. |       |
| `user_id`, `user_login`, `day`, `enterprise_id`, `team_id``slug`   |                                                  |       |

같은 날 여러 팀에 속한 사용자가 쌍당 `(user, team)` 한 행씩 여러 행에 표시됩니다.

> \[!IMPORTANT]
> **사용자 Copilot 수가 5명 미만인 팀은 사용자 팀 보고서에서 제외됩니다.**
>
> 의미:
>
> * 지정된 날짜에 사용자 수가 5명 미만인 팀은 해당 구성원 Copilot 이 활동을 하더라도 해당 날짜의 사용자 팀 보고서에 표시되지 않습니다. 활동은 사용자별 사용 메트릭 보고서에 여전히 있지만 조인 결과에는 팀 행이 없습니다.
> * 여러 날에 걸친 기간 동안 임계값을 넘는 팀은 어떤 날에는 존재하고 다른 날에는 존재하지 않습니다. 팀이 임계값을 초과한 날만 합계에 기여합니다.
> * 팀 행을 다시 합산하여 엔터프라이즈 또는 조직 합계와 비교하면 합계가 엔터티 합계보다 낮습니다. 부족한 것은 하위 임계값 팀에만 속한 사용자의 활동이며, 참가 결과에 팀 행이 없으므로 해당 활동이 팀 집계에 표시되지 않습니다.

### 사용자별 사용 메트릭 보고서

이러한 보고서에는 지정된 날짜에 Copilot 대한 각 사용자의 활동이 포함됩니다.

| Report                                                               | Scope                                                                                | 주요 필드 |
| :------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :---- |
| `organization_users_1_day`                                           | 각 `(user_id, day, organization_id)`별로 한 행씩, 해당 조직 내에서 사용자가 그날 수행한 Copilot 활동이 표시됩니다. |       |
| `user_id`, `day`, `organization_id`, `enterprise_id`, 활동 카운터, 세분화 배열 |                                                                                      |       |
| `users_1_day`                                                        | 각 `(user_id, day, enterprise_id)`별로 한 행씩, 해당 기업 내에서 사용자가 그날 수행한 Copilot 활동이 표시됩니다.   |       |
| `user_id`, `day`, `enterprise_id`, 활동 카운터, 세분화 배열                    |                                                                                      |       |

이러한 보고서에서 사용할 수 있는 필드의 전체 목록은 [Copilot 사용 메트릭에서 사용할 수 있는 데이터](/ko/copilot/reference/copilot-usage-metrics/copilot-usage-metrics)을 참조하세요.

> \[!WARNING]
> 28일 롤링 사용자별 보고서(`users_28_day`, `organization_users_28_day`)를 일일 사용자-팀 보고서와 조인하지 마세요. 사용자-팀 보고서는 특정 하루의 팀 멤버십을 반영하므로, 28일간의 활동 데이터를 단일 날짜의 멤버십 스냅샷과 결합하면 전체 28일의 활동이 조인한 날짜에 사용자가 속해 있던 팀에 귀속됩니다. 이로 인해 해당 기간 동안 팀 소속이 변경되면 활동이 잘못된 팀에 귀속됩니다. 항상 일별 활동 데이터를 일별 사용자 팀 데이터와 조인한 후, 원하는 집계 기간으로 집계하세요.

### 개체 수준 보고서

엔터티 수준 보고서(`enterprise_28_day`, `organization_28_day`, ,`enterprise_1_day``organization_1_day`)는 전체 엔터프라이즈 또는 조직에 대해 미리 집계된 합계입니다. 이들에는 `user_id` 또는 `team_id`가 포함되지 않으며, 팀별 세부 분석을 생성하기 위해 사용자-팀 보고서와 결합할 수 없습니다. 엔터프라이즈 또는 조직 합계를 원하는 경우 직접 사용합니다. 팀 수준 합계의 경우 아래에 설명된 일일 사용자 팀 + 일일 사용자별 메트릭 조인을 사용합니다.

## Example

이 최소한의 엔드 투 엔드 예제는 조직 팀 메트릭의 1일을 생성합니다. 각 입력 보고서에 대한 아래 샘플 NDJSON 행은 해당 보고서 중 하나에서 다운로드한 파일에서 찾을 수 있는 행과 같습니다(위의 보고서 `download_links`[가져오기](#fetching-the-reports) 참조).

조직 Copilot에서 2026-05-07에 `999` 활동이 있는 사용자는 두 명입니다.

* **Alice** (`user_id=1001`)는 그날 두 팀, 즉 `frontend` (`team_id=42`) 및 `backend` (`team_id=43`)에 속해 있습니다.
* **Bob**(`user_id=1002`)은 (`frontend`)에 `team_id=42` 만 속합니다.

### 입력: `organization_user_teams_1_day`

```json
{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "team_id": 42, "slug": "frontend"}
{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "team_id": 43, "slug": "backend"}
{"user_id": 1002, "user_login": "bob",   "day": "2026-05-07", "organization_id": "999", "team_id": 42, "slug": "frontend"}
```

Alice는 자신이 속한 팀당 한 행씩 두 번 나타납니다.

### 입력: `organization_users_1_day`

```json
{"user_id": 1001, "user_login": "alice", "day": "2026-05-07", "organization_id": "999", "enterprise_id": "13213",
 "user_initiated_interaction_count": 50, "code_generation_activity_count": 40, "code_acceptance_activity_count": 12,
 "loc_suggested_to_add_sum": 200, "loc_added_sum": 88, "used_chat": true,  "used_agent": true,  ...}
{"user_id": 1002, "user_login": "bob",   "day": "2026-05-07", "organization_id": "999", "enterprise_id": "13213",
 "user_initiated_interaction_count": 30, "code_generation_activity_count": 25, "code_acceptance_activity_count": 7,
 "loc_suggested_to_add_sum": 80,  "loc_added_sum": 24, "used_chat": true,  "used_agent": false, ...}
```

`(user, day, organization)`당 한 행. 활동 합계는 모든 표면에서 합산된 날짜에 대한 것입니다.

### 조인 및 집계된 결과

두 보고서를 `(user_id, day, organization_id)`을 기준으로 내부 조인한 다음 `team_id`별로 그룹화하고 집계합니다. 아래 열은 `active_users` 사용자별 보고서의 필드가 아닌 집계 출력(`COUNT(DISTINCT user_id)`)입니다. 나머지 숫자 열은 일치하는 보고서 필드의 합계입니다.

| team\_id | 슬러그      | 활성 사용자 | 코드 수락 활동 수 | loc\_added\_sum |
| :------- | :------- | :----- | :--------- | :-------------- |
| 42       | frontend | 2      | 19         | 응급 전화번호 112     |
| 43       | 백엔드      | 1      | 12         | 88              |

팀마다 하나씩, 총 두 개의 팀별 일일 행. 이 행은 `frontend` Alice와 Bob의 활동을 모두 집계합니다. 행에는 `backend` Alice의 활동만 포함됩니다.

Alice의 활동은 **두 팀 모두** 에 기여합니다. 그녀의 행에 있는 12와 88은 `frontend`에 포함되고, `backend`에도 다시 포함됩니다. 이는 팀 수준 지표의 의도와 일치합니다. 즉, 각 팀은 자기 구성원의 활동을 볼 수 있지만, 두 팀의 행을 다시 하나의 조직 총계로 합산하면 Alice가 중복 집계됩니다. 조직 합계의 경우 사용자 팀 참가 없이 직접 쿼리 `organization_users_1_day` 합니다.

## 팀 수준 메트릭을 생성하는 방법

모든 팀 수준 조각의 경우 동일한 4단계가 적용됩니다.

1. **보고서 쌍을 선택합니다.**

   * 조직 팀의 경우 `organization_user_teams_1_day`을(를) `organization_users_1_day`와 페어링하세요. 공유 엔터티 ID는 .입니다 `organization_id`.
   * 엔터프라이즈 및 비즈니스 팀의 경우 `enterprise_user_teams_1_day`을(를) `users_1_day`과 페어링하세요. 공유 엔터티 ID는 .입니다 `enterprise_id`.

2. **두 보고서를 내부 조인**합니다(`(user_id, day, entity_id)` 기준). 세 키는 모두 일치해야 합니다. 조인은 팀 측에서 일대다 관계입니다. 한 사용자가 여러 팀에 속한 경우 여러 사용자-팀 행과 일치합니다.

3. \*\*
   `day` 기준으로 필터링\*\*하여 원하는 날짜로 지정하세요. 두 보고서 모두 동일한 `day` 값을 전달합니다.

4. \*\*
   `team_id`별로 그룹화\*\*하고 (`slug`는 팀의 표시 이름으로) 집계합니다. 사용:

   * `COUNT(DISTINCT user_id)`: 활성 사용자와 같은 고유 사용자 수의 경우.
   * `SUM(...)` 볼륨 카운터의 경우(예를 들어 `code_generation_activity_count`, `loc_added_sum` 및 `user_initiated_interaction_count`)

조인은 내부 조인입니다. 팀은 그 날 적어도 한 명의 멤버가 활동을 한 경우에만 지정된 날짜의 결과에 나타납니다. 해당 날짜에 활동이 없었던 팀을 나열하려면 사용자-팀 보고서에서 왼쪽 조인하고 null 카운터를 0으로 처리합니다.

### 언어, IDE, 기능 또는 모델별 절단

차원별 세부 내역은 각 사용자 행의 배열 필드(`totals_by_ide`, `totals_by_language_feature`, `totals_by_language_model`, `totals_by_model_feature`)에 저장됩니다. 차원별로 그룹화하려면 조인의 일부로 관련 배열을 확장하고, 그룹화에 차원 열을 추가하고, 해당 차원으로 범위가 지정된 요소별 카운터를 집계합니다.
`language` 및 `ide`는 각각 별도의 배열에 있으므로, 팀 수준의 `(language × ide)` 교차 탭을 만들려면 애플리케이션에서 두 개의 쿼리를 결합해야 합니다.

### 롤링 창 팀 보고서 빌드

롤링 창 팀 보고서(예: 28일 롤업)를 생성하려면 다음을 실행합니다.

1. 창에서 매일 매일 엔드포인트를 호출합니다.
2. 매일의 사용자별 사용량 메트릭 보고서(`organization_users_1_day` 또는 `users_1_day`)를 같은 날의 사용자-팀 보고서(`organization_user_teams_1_day` 또는 `enterprise_user_teams_1_day`)와 `(user_id, day, entity_id)`에서 조인하세요.
3. 창에 맞게 `day`를 필터링하고 그룹화에서 `day` 제거합니다.

볼륨 카운터는 일자별로 누적되므로, 해당 기간 동안 합산하세요. 고유 사용자 수는 전체 창의 조인된 `COUNT(DISTINCT user_id)` 행에 대해 계산되어야 하며, 일별 개수로 합계를 계산할 수 없습니다.

일일 참가는 사용자가 해당 날짜에 어떤 팀에 있었는지에 따라 매일의 활동을 보장**합니다.** 이것이 없으면 해당 기간 동안 팀 구성 변경 사항으로 인해 활동이 알림 없이 잘못된 팀에 잘못 귀속됩니다.

## 제한 사항 및 주의 사항

* **여러 팀의 사용자가 소속된 각 팀에 기여합니다.** 팀별 행을 다시 조직 또는 엔터프라이즈 전체 합계에 합산할 때는 주의하세요. 여러 팀에 속한 사용자가 중복 집계될 수 있습니다. 조직 또는 엔터프라이즈 합계에 사용자별 보고서를 직접 사용합니다(사용자 팀 참가 제외).
* **하위 임계값 팀은 사용자 팀 보고서에 없습니다.** 지정된 날짜에 사용자 Copilot 수가 5명 미만인 팀은 제외되므로 활동은 사용자별 보고서에 아직 있더라도 팀 수준 결과에 표시되지 않습니다.
* **고유 사용자 수는 일 단위로 합계를 계산할 수 없습니다.** 여러 날에 걸친 기간에 대해 롤업할 때는 일별 개수를 합산하지 말고 전체 기간의 조인된 행 전체에 대해 `COUNT(DISTINCT user_id)`를 평가합니다.
* **더 많은 기능 표면이 추적됩니다.** 볼륨 카운터(`code_generation_activity_count`, `code_acceptance_activity_count`, 및 `loc_*` 카운터)는 여러 Copilot 표면(인라인 IDE 완성, 채팅 패널 작업, 그리고 수락된 줄 수 카운터의 경우 Copilot agent 편집) 전반의 활동을 집계합니다. 카운터별 노출 범위 세부 정보는 [Copilot 사용 메트릭에서 사용할 수 있는 데이터](/ko/copilot/reference/copilot-usage-metrics/copilot-usage-metrics)을 참조하세요. 이전에 인라인 IDE 완성만 집계하던 인터페이스에서 유사한 메트릭을 확인했다면, 이 카운터들의 값이 더 높아질 수 있으므로 컷오버 전후를 비교하기보다는 기준선을 다시 설정하세요.
* **새 차원을 활용합니다.** 각 사용자 행에서 IDE별, 기능별, `(language, feature)`별, `(language, model)`별, `(model, feature)`별 세부 내역을 확인할 수 있으며, 이를 통해 이전의 팀 메트릭 화면에서는 지원되지 않던 팀 수준 보고서를 생성할 수 있습니다.

## 다음 단계

* 사용자별 사용 메트릭 보고서에 대한 전체 스키마 및 필드 참조는 [Copilot 사용 메트릭에서 사용할 수 있는 데이터](/ko/copilot/reference/copilot-usage-metrics/copilot-usage-metrics)을 참조하세요.
* 예를 들어 사용 메트릭 엔드포인트의 JSON 페이로드는 [Copilot 사용 메트릭에 대한 예제 스키마](/ko/copilot/reference/copilot-usage-metrics/example-schema)을 참조하세요.
* 대시보드, API 및 내보내기에서 메트릭을 조정하는 방법에 대한 지침은 [대시보드, API 및 보고서에서 Copilot 사용량 메트릭 조정](/ko/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics)을 참조하세요.