> For the complete documentation index, see [llms.txt](https://docs.smply.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smply.one/saas-integration/guide-main/gemini.md).

# Gemini

## Gemini

Google Cloud의 **Gemini Code Assist**를 심플리에 연동하면 조직의 코드 어시스턴트 사용량과 활동을 한 곳에서 확인할 수 있습니다. 심플리 전용 서비스 계정에 GCP 프로젝트의 모니터링 조회 권한을 부여한 뒤, 해당 **GCP 프로젝트 ID**를 등록하는 방식입니다. 하나의 워크스페이스에 여러 GCP 프로젝트를 등록할 수 있고, 매일 자동으로 최신 사용량이 동기화됩니다.

연동 설정 화면과 사이드바 카드에는 **Gemini Code Assist**로 표시됩니다. 이 연동은 GCP 프로젝트의 Code Assist 사용량 조회 기능이며, **Gemini Enterprise 구독과는 별개**입니다.

{% hint style="info" %}
**조회 전용 연동입니다**

심플리는 GCP Cloud Monitoring에 기록된 Code Assist 메트릭을 **조회**만 합니다. 라이선스 할당이나 사용량 제어 같은 변경은 수행하지 않으며, GCP 프로젝트에 어떤 변경도 가하지 않습니다.
{% endhint %}

***

### 1. 주요 기능

| 기능         | 설명                            |
| ---------- | ----------------------------- |
| **활성 사용자** | 일일/주간/28일 활성 사용자 수            |
| **코드 제안**  | 제안 수, 승인 수, 제안 승인률, 승인된 코드 라인 |
| **채팅 활동**  | 채팅 대화·응답 수                    |
| **토큰 사용량** | 입력/출력/캐시 토큰 및 API 호출 수        |

연동 후 사용량은 **AI → Gemini** 메뉴의 대시보드에서 확인합니다. 자세한 화면 구성은 아래 **4. 대시보드 확인**을 참고하세요.

***

### 2. 연동하기

심플리는 자체 **서비스 계정**으로 고객사 GCP 프로젝트의 Cloud Monitoring 메트릭을 읽습니다. 따라서 별도의 키를 발급해 붙여넣는 대신, **GCP 프로젝트에 심플리 서비스 계정을 추가**하고 **프로젝트 ID를 등록**하는 순서로 진행합니다.

{% hint style="info" %}
**필요한 준비물**

* **GCP 프로젝트**: Gemini Code Assist가 활성화된 Google Cloud 프로젝트.
* **GCP 프로젝트 ID**: 등록할 프로젝트의 ID (예: `my-gcp-project-123`). 프로젝트 이름이 아니라 ID입니다.
* **GCP IAM 권한**: 해당 프로젝트에서 서비스 계정에 역할을 부여할 수 있는 권한(예: 프로젝트 IAM 관리자).
* **심플리 관리자 권한**: 심플리에서 연동을 설정할 수 있는 권한.
  {% endhint %}

**단계 1: 심플리 서비스 계정 확인**

1. 심플리 사이드바에서 **설정** > **연동 관리**로 이동해 **Gemini Code Assist** 카드를 엽니다.
2. **서비스 계정** 영역에 *"GCP 프로젝트에 다음 서비스 계정을 추가해주세요:"* 안내와 함께 심플리 서비스 계정 이메일이 표시됩니다.
3. **`이메일 복사`** 버튼으로 서비스 계정 이메일을 복사합니다.

<figure><img src="/files/NUsVBmltWXxZaQ0GSWGR" alt="Gemini Code Assist 연동 설정 화면 — 서비스 계정 카드와 GCP 프로젝트 카드"><figcaption></figcaption></figure>

{% hint style="info" %}
**서비스 계정 이메일은 화면 값을 사용하세요**

서비스 계정 이메일은 설정 화면에 표시되는 값을 그대로 복사해 사용하세요. 화면의 **`이메일 복사`** 버튼을 쓰면 오타 없이 정확히 복사됩니다.
{% endhint %}

**단계 2: GCP 프로젝트에 서비스 계정 권한 부여**

1. [Google Cloud Console](https://console.cloud.google.com)에서 연동할 프로젝트로 이동합니다.
2. **IAM 및 관리자 → IAM**에서 **액세스 권한 부여**를 선택합니다.
3. **새 주 구성원**에 단계 1에서 복사한 심플리 서비스 계정 이메일을 붙여넣습니다.
4. 모니터링 메트릭을 조회할 수 있는 역할(**모니터링 뷰어** 수준)을 부여하고 저장합니다.

{% hint style="info" %}
**Gemini Code Assist 메트릭이 수집되는 프로젝트여야 합니다**

심플리는 Cloud Monitoring의 Code Assist 지표를 조회합니다. Gemini Code Assist가 활성화되어 사용량 메트릭이 쌓이고 있는 프로젝트를 등록해야 데이터가 표시됩니다.
{% endhint %}

**단계 3: 심플리에 프로젝트 ID 등록**

1. 다시 심플리 **Gemini Code Assist** 연동 설정 화면의 **GCP 프로젝트** 영역으로 이동합니다.
2. *"Gemini Code Assist가 활성화된 GCP 프로젝트 ID를 입력해주세요."* 안내에 따라 **`GCP 프로젝트 ID`** 입력란에 프로젝트 ID를 입력합니다. (placeholder: `my-gcp-project-123`)
3. **`프로젝트 추가`** 버튼을 클릭합니다.

심플리는 프로젝트를 추가할 때 입력한 프로젝트의 Code Assist 메트릭에 접근이 가능한지 자동으로 확인합니다. 확인 결과에 따라 프로젝트 상태가 아래와 같이 표시됩니다.

| 상태        | 의미                                                              |
| --------- | --------------------------------------------------------------- |
| **인증됨**   | 메트릭 접근이 정상 확인되었습니다.                                             |
| **대기 중**  | 권한은 확인됐으나 아직 표시할 사용량 데이터가 없습니다. 권한 부여 직후이거나 메트릭이 쌓이기 전일 수 있습니다. |
| **인증 실패** | 메트릭에 접근할 수 없습니다. 권한 또는 프로젝트 ID를 다시 확인하세요.                       |

{% hint style="success" %}
**연동 완료**

프로젝트가 정상 확인되면 연동 상태가 **연동됨**으로 표시되고, 사용량 동기화가 자동으로 시작됩니다. 잠시 후 **AI → Gemini** 메뉴에서 대시보드를 확인할 수 있습니다.
{% endhint %}

***

### 3. 여러 프로젝트 관리

하나의 심플리 워크스페이스에 여러 GCP 프로젝트를 등록할 수 있습니다. 등록된 프로젝트는 연동 설정 화면의 목록에서 프로젝트 ID와 상태(**인증됨**/**대기 중**/**인증 실패**)와 함께 확인됩니다.

**프로젝트 추가**

1. **GCP 프로젝트** 영역의 **`GCP 프로젝트 ID`** 입력란에 추가할 프로젝트 ID를 입력합니다.
2. **`프로젝트 추가`** 버튼을 클릭합니다. (각 프로젝트도 단계 2의 서비스 계정 권한 부여가 되어 있어야 합니다.)

**연결 확인**

* 상태가 **대기 중** 또는 **인증 실패**인 프로젝트는 **`연결 확인`** 버튼으로 접근 가능 여부를 다시 확인할 수 있습니다. 권한을 부여한 직후 상태를 갱신할 때 사용합니다.

**프로젝트 제거**

* 프로젝트 우측의 휴지통 아이콘을 클릭하면 해당 프로젝트만 목록에서 제거됩니다. 다른 프로젝트 연동에는 영향이 없습니다.

<figure><img src="/files/3JTNUaXZ4w5mxE3FBKkN" alt="Gemini Code Assist 등록 프로젝트 목록 — 프로젝트별 ID·상태 뱃지와 제거 아이콘"><figcaption></figcaption></figure>

***

### 4. 대시보드 확인

연동 후 사용량은 **AI → Gemini** 메뉴에서 확인합니다. 연동 설정 화면의 **`대시보드 보기`** 버튼으로도 이동할 수 있습니다.

대시보드는 다음으로 구성됩니다.

| 영역         | 표시 내용                                                 |
| ---------- | ----------------------------------------------------- |
| **요약 카드**  | 일일 활성 사용자, 28일 활성 사용자, 제안 승인률, 승인된 코드 라인, 채팅 활동, 총 토큰 |
| **사용량 추이** | 기간별 사용량 추세 그래프                                        |
| **상세 표**   | 날짜·프로젝트별 사용자·제안·승인·승인된 코드 라인·채팅·API 호출·토큰             |

{% hint style="info" %}
**연결 전에는 빈 화면이 표시됩니다**

연동이 없거나 아직 데이터가 수집되지 않은 경우 대시보드에는 *"Gemini Code Assist가 연결되지 않았습니다."* 안내가 표시됩니다. 연동을 마치고 첫 동기화가 끝나면 데이터가 채워집니다.
{% endhint %}

***

### 5. 동기화

연동된 프로젝트의 사용량은 **매일 오전 5시(한국 시간)** 자동으로 동기화됩니다.

* **첫 연동 시점**: 프로젝트를 추가해 정상 확인되면 즉시 한 차례 동기화가 실행됩니다. 처음에는 최근 약 한 달치 사용량을 한 번에 가져옵니다.
* **이후**: 마지막 동기화 시점 이후의 데이터만 매일 이어서 채웁니다.
* 연동 직후에는 첫 동기화가 끝날 때까지 대시보드에 데이터가 보이지 않을 수 있으며, 동기화가 끝나면 반영됩니다.

{% hint style="info" %}
**메트릭 제공 시점에 따른 지연**

사용량은 GCP Cloud Monitoring에 메트릭이 기록된 뒤 조회되므로, 가장 최근 데이터(특히 당일·전일)는 메트릭 적재 주기에 따라 다소 늦게 반영될 수 있습니다.
{% endhint %}

***

### 6. 연동 해제

연동 해제는 두 가지로 나뉩니다.

| 동작          | 설명                                                    |
| ----------- | ----------------------------------------------------- |
| **프로젝트 제거** | 특정 GCP 프로젝트 하나만 목록에서 제거합니다. 다른 프로젝트 연동에는 영향이 없습니다.    |
| **연동 해제**   | Gemini Code Assist 연동 전체를 해제합니다. 모든 프로젝트의 동기화가 중단됩니다. |

전체 연동을 해제하려면 연동 상태 영역의 **`연동 해제`** 버튼을 클릭합니다. *"Gemini Code Assist 연동을 해제하시겠습니까?"* 확인 후 진행하면 *"연동 해제 후에는 관련 데이터 동기화가 중단됩니다."*

{% hint style="warning" %}
**연동 해제 후 동기화 중단**

연동을 해제하면 데이터 동기화가 중단됩니다. 이미 수집된 사용량 데이터는 유지되지만 더 이상 최신 상태로 갱신되지 않습니다.
{% endhint %}

***

### 7. 문제 해결

#### Q: 프로젝트 추가가 실패하거나 \*"인증 실패"\*로 표시됩니다

**원인 1: IAM 권한 부족**

* 연동 설정 화면에 표시된 심플리 서비스 계정이 해당 GCP 프로젝트의 IAM에 추가되어 있는지 확인하세요.
* 모니터링 메트릭을 조회할 수 있는 역할(모니터링 뷰어 수준)이 부여되어 있는지 확인하세요. 권한이 없으면 *"IAM 권한이 없습니다. 서비스 계정에 프로젝트 접근 권한을 부여해주세요."* 안내가 표시됩니다.
* 권한을 부여한 직후라면 **`연결 확인`** 버튼으로 상태를 다시 확인하세요.

**원인 2: 잘못된 프로젝트 ID**

* 입력한 값이 프로젝트 **이름**이 아니라 프로젝트 **ID**인지 확인하세요. 존재하지 않으면 *"프로젝트를 찾을 수 없습니다."* 안내가 표시됩니다.
* 프로젝트 ID 앞뒤에 공백이 포함되지 않았는지 확인하세요.

#### Q: 데이터가 보이지 않고 상태가 \*"대기 중"\*입니다

* 권한은 확인됐지만 아직 표시할 사용량 메트릭이 없는 상태입니다. Gemini Code Assist가 실제로 사용되어 Cloud Monitoring에 메트릭이 쌓이면 데이터가 채워집니다.
* 연동 직후라면 첫 동기화가 끝날 때까지 기다린 뒤 다시 확인하세요.

#### Q: 사용량 데이터가 늦게 반영됩니다

* 사용량은 매일 자동 동기화됩니다. 가장 최근 데이터는 GCP의 메트릭 적재 주기에 따라 반영이 다소 늦을 수 있습니다.
* 연동 직후에는 첫 동기화가 끝나기 전까지 데이터가 비어 있을 수 있습니다.

#### Q: 여러 프로젝트를 연동할 수 있나요

네. 하나의 심플리 워크스페이스에 여러 GCP 프로젝트를 등록할 수 있습니다. 프로젝트별로 개별 추가·제거가 가능하며, 각 프로젝트마다 서비스 계정 권한 부여가 필요합니다.

#### Q: Gemini Enterprise 구독도 여기서 관리되나요

아니요. 이 연동은 GCP 프로젝트의 **Gemini Code Assist** 사용량을 다룹니다. Gemini Enterprise 구독과는 별개입니다.

#### Q: 이 외의 문제

채널톡으로 문의해 주세요.