> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rootly

> Kết nối Rootly để agent có thể phân loại sự cố đang mở, xem xét cảnh báo và tạo các action item theo dõi mà một sự cố để lại

Kết nối Rootly để các agent CloudThinker có thể liệt kê sự cố đang mở và gần đây, kiểm tra cảnh báo nào đã trở thành sự cố, và theo dõi các action item (tác vụ theo dõi gắn với một sự cố) vẫn còn tồn đọng sau khi xử lý. Kết nối dùng một **API key** Rootly. Agent đọc tự do và chỉ có thể thực hiện một loại thay đổi: action item của sự cố.

## Điều kiện tiên quyết

* Quyền truy cập **Organization Settings** trong Rootly, nơi tạo API key.
* Quyền chỉnh sửa kết nối trong workspace CloudThinker của bạn.

## Thiết lập

**1. Tạo API key trong Rootly**

Trong Rootly, mở menu tổ chức ở góc trên bên trái và vào **Organization Settings → API Keys**. Nhấn **Generate New API Key**, đặt tên `cloudthinker` và chọn scope **Global** để key có thể đọc sự cố của mọi team.

Sao chép key ngay. Rootly chỉ hiển thị key một lần, nên mất key nghĩa là phải tạo key mới.

**2. Thêm kết nối trong CloudThinker**

Trên thanh bên, nhấn **More → Workspace settings → Connections**. Ở tab **Builtin Connections**, tìm **Rootly** và nhấn **Connect**.

Dán key vào **API Key** và nhấn **Connect**. CloudThinker kiểm tra key với Rootly API.

**Trạng thái thành công:** kết nối hiển thị **Connected**, và thông báo kiểm tra nêu tên người dùng của key, ví dụ `Rootly connection verified (Jane Doe)`.

## Chi tiết kết nối

| Trường | Mô tả | Ví dụ |
| - | - | - |
| **API Key** | Rootly API key từ **Organization Settings → API Keys** | `<your-api-key>` |

Không cần nhập endpoint hay region. CloudThinker gọi trực tiếp `https://api.rootly.com/v1`.

## Quyền yêu cầu

Rootly giới hạn scope của key khi bạn tạo key và không có danh sách quyền theo từng endpoint, nên scope là cách kiểm soát duy nhất.

| Scope của key | Agent thấy gì |
| - | - |
| **Global** | Sự cố, cảnh báo và action item của mọi team. Khuyến nghị. |
| **Team** | Dữ liệu của một team. Dùng khi agent không được thấy gì khác. |
| **Personal** | Chỉ những gì người dùng đó thấy được. |

> [!TIP]
>
> Key Team hoặc Personal vẫn kết nối được. Khi đó các thao tác đọc danh sách trả về ít dòng hơn mà không báo lỗi, trông như một tài khoản ít hoạt động. Đọc một mục cụ thể nằm ngoài scope của key trả về `403`. Nếu số liệu có vẻ thấp, hãy kiểm tra scope của key trước.

## Khả năng của agent

| Khả năng | Agent có thể làm gì | Được Approvals kiểm tra |
| - | - | - |
| **Khám phá** | Đọc người dùng của key và tên severity, team, service, environment và incident type của tài khoản | Không |
| **Phân loại sự cố** | Liệt kê sự cố đang mở và gần đây với trạng thái, severity, loại, service bị ảnh hưởng, team xử lý, mốc thời gian và liên kết | Không |
| **Xem xét cảnh báo** | Liệt kê cảnh báo với trạng thái, nguồn, mức khẩn cấp, service sở hữu, và cảnh báo đó có trở thành sự cố hay không | Không |
| **Theo dõi việc tồn đọng** | Liệt kê action item của một sự cố, người phụ trách từng mục và mục nào còn tồn đọng | Không |
| **Ghi action item** | Tạo, cập nhật hoặc xóa action item của sự cố, mỗi lần một mục | Có |

### Mặc định và giới hạn

| Thao tác đọc | Khoảng thời gian mặc định | Số dòng mặc định | Số dòng tối đa |
| - | - | - | - |
| Sự cố | 168 giờ gần nhất (7 ngày), theo thời điểm bản ghi được tạo | 20 | 100 |
| Cảnh báo | 24 giờ gần nhất | 25 | 100 |
| Action item (toàn tài khoản) | 720 giờ gần nhất (30 ngày) | 25 | 100 |
| Khám phá | Không giới hạn thời gian | 15 mỗi mục | 100 |

Mọi câu trả lời đều cho biết đã đọc bao nhiêu dòng và Rootly khớp được bao nhiêu. Nếu câu trả lời ghi `truncated`, hãy yêu cầu khoảng thời gian ngắn hơn hoặc nhiều dòng hơn trước khi coi con số đó là tổng.

Sự cố loại `test` hoặc `example` là diễn tập. Các sự cố này vẫn được tính, trừ khi bạn yêu cầu agent loại trừ.

### Xác minh kết nối

```text theme={null}
Run Rootly discovery and summarize the key's user, the severity names this account uses, and how many teams and services you can read
```

Kết nối hoạt động sẽ liệt kê tên severity của riêng bạn, chẳng hạn `SEV1` và `SEV2`. Lỗi có nhắc đến `403` nghĩa là key quá hẹp.

### Ví dụ prompt

```text theme={null}
List the Rootly incidents still open right now, with severity and impacted services
Which Rootly alerts from the last 24 hours never became an incident?
What action items are still owed on the most recent SEV1 incident, and who owns each one?
```

## Quyền ghi

Agent không thể khai báo, cập nhật, giải quyết hoặc xóa một sự cố Rootly. Khai báo sự cố qua API sẽ chạy các workflow thật của tài khoản: các workflow này có thể mở kênh Slack, thông báo cho người theo dõi và page người trực on-call. Xóa sự cố sau đó không hoàn tác được những việc này, nên mọi thay đổi với sự cố vẫn phải thực hiện trong Rootly.

Thay đổi duy nhất agent có thể thực hiện là với action item của sự cố: tạo, cập nhật hoặc xóa. Action item gắn với một sự cố có sẵn và không thay đổi trạng thái của sự cố đó. Tài khoản Rootly của bạn vẫn có thể có workflow kích hoạt theo action item, và CloudThinker không thấy được bạn đã bật những workflow nào.

Cách một thao tác ghi diễn ra:

1. Agent tìm ID của sự cố hoặc action item bằng một thao tác đọc trước. Agent không bao giờ đoán ID.
2. Thay đổi đi qua Rule và chế độ [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của bạn.
3. Agent thực hiện một thay đổi cho mỗi lần phê duyệt, rồi đọc lại mục đó và báo cáo thay đổi đã có hay chưa. Rootly trả về `200` kể cả với lần cập nhật không thay đổi gì, nên việc đọc lại là bằng chứng.

**Allow writes** được bật theo mặc định. Để giữ kết nối chỉ đọc, vào **More → Workspace settings → Connections**, chọn **Rootly** và tắt **Allow writes**. Khi đó agent từ chối mọi thay đổi.

## Khắc phục sự cố

> **Rootly rejected the API key**
>
> Rootly trả về `401`. Key được sao chép không đầy đủ hoặc đã bị thu hồi. Tạo key mới trong **Organization Settings → API Keys**, rồi mở kết nối Rootly trong CloudThinker và thay giá trị đã lưu.

> **Rootly accepted the key but refused the request**
>
> Rootly trả về `403`. Key có thể có scope Team hoặc Personal, hoặc role trên key Global đã bị thu hẹp. Tạo key Global, giữ nguyên role và cập nhật kết nối.

> **Câu hỏi có lọc không trả về gì**
>
> Rootly trả về danh sách trống, không phải lỗi, với tên severity, team hoặc service mà tài khoản không dùng. Yêu cầu agent chạy khám phá trước, rồi hỏi lại với đúng các tên mà agent trả về, chẳng hạn `SEV1` thay vì `Critical`.

> **Rootly rate-limited the request**
>
> Rootly trả về `429`. Giới hạn là 3.000 lượt đọc mỗi API key mỗi phút. Đợi một phút rồi thử lại. Kết nối lại không đặt lại giới hạn.

> **Một thay đổi action item không được áp dụng**
>
> Nếu thay đổi bị từ chối hoặc **Allow writes** đang tắt, không có gì được gửi tới Rootly. Nếu bạn đã phê duyệt và yêu cầu bị hết thời gian chờ, hãy yêu cầu agent liệt kê action item của sự cố trước khi thử lại. Thử lại mù quáng có thể tạo cùng một mục hai lần.

## Bảo mật

* **Quyền tối thiểu** — chỉ cấp các quyền mà agent cần cho trường hợp sử dụng của bạn; bắt đầu với quyền chỉ đọc và mở rộng sau.
* **Chỉ đọc theo mặc định** — sử dụng thông tin xác thực chỉ đọc trừ khi bạn muốn agent thực hiện thay đổi qua kết nối này.
* **Xoay vòng thông tin xác thực** — xoay vòng khóa và token theo lịch trình thông thường của bạn; CloudThinker sẽ lấy giá trị mới khi bạn cập nhật kết nối.
* **Thu hồi khi bàn giao** — xóa thông tin xác thực tại nhà cung cấp khi bạn xóa một kết nối hoặc khi đồng nghiệp rời nhóm.

- **Key Global có phạm vi rộng.** Key Global đọc sự cố của mọi team. Dùng key Team khi agent chỉ nên thấy một team.
- **Một đường ghi duy nhất.** Chỉ thay đổi action item mới đến được Rootly, và **Allow writes** có thể tắt hoàn toàn chúng.

## Liên quan

> **[Kết nối PagerDuty](https://docs.cloudthinker.io/vi/guide/connections/pagerduty.md)**
>
> Gửi sự cố PagerDuty tới Resolve để phân tích nguyên nhân gốc

> **[Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md)**
>
> Kiểm soát thay đổi action item nào phải chờ người duyệt


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.