> ## 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.

# SigNoz

> Kết nối SigNoz với CloudThinker để điều tra độ trễ dịch vụ, tìm kiếm log, kiểm tra quy tắc cảnh báo và đi sâu vào distributed trace

Kết nối instance SigNoz của bạn để cho phép các agent CloudThinker điều tra độ trễ dịch vụ, tìm kiếm và tổng hợp log, kiểm tra quy tắc cảnh báo và đi sâu vào distributed trace trên toàn bộ stack của bạn.

SigNoz xác thực bằng **Service Account API key** được giới hạn phạm vi theo vai trò (`signoz-viewer` để truy cập chỉ đọc, `signoz-admin` để truy cập ghi).

***

## Các nền tảng được hỗ trợ

| Nền tảng                | Hỗ trợ                  |
| ----------------------- | ----------------------- |
| **SigNoz Cloud**        | Tất cả tenant           |
| **SigNoz (tự lưu trữ)** | Các instance tự quản lý |

SigNoz Cloud và tự lưu trữ dùng chung giao diện, vì vậy các bước thiết lập dưới đây giống nhau cho cả hai.

***

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

* Một **instance SigNoz Cloud hoặc tự lưu trữ**.
* Một **Service Account** để tạo API key (dùng `signoz-viewer` để truy cập chỉ đọc hoặc `signoz-admin` nếu CloudThinker cần thực hiện thay đổi).
* **URL cơ sở SigNoz** của bạn.

***

## Thiết lập

<Steps>
  <Step title="Tạo service account">
    Trong SigNoz, mở **Settings → Workspace Settings → Service Accounts** và nhấn **New Service Account**. Nhập tên (ví dụ `cloudthinker-svc`) và nhấn **Create Service Account**.
  </Step>

  <Step title="Gán vai trò">
    Trên tab **Overview**, dùng dropdown **Roles** để chọn `signoz-viewer` để truy cập chỉ đọc hoặc `signoz-admin` nếu CloudThinker cần thực hiện thay đổi. Nhấn **Save Changes** để vai trò có hiệu lực.
  </Step>

  <Step title="Tạo API key">
    Chuyển sang tab **Keys** và nhấn **Add Key**. Nhập tên key (ví dụ `cloudthinker-key`), tùy chọn đặt ngày hết hạn, nhấn **Create Key** và sao chép key.
  </Step>

  <Step title="Thêm kết nối trong CloudThinker">
    Điều hướng đến **Connections → SigNoz** và nhập:

    * **SigNoz URL**: URL cơ sở của instance, ví dụ `https://<hash>.signoz.cloud` (chỉ URL cơ sở, không có path, nếu không các yêu cầu sẽ trả về 404)
    * **API Key**: key vừa sao chép
    * **Log Level** (tùy chọn): giữ là `info` trừ khi bạn đang gỡ lỗi

    Nhấn **Connect**. CloudThinker xác minh thông tin xác thực và hiển thị trạng thái **Connected**.
  </Step>
</Steps>

***

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

| Trường               | Mô tả                                                                | Ví dụ                         |
| -------------------- | -------------------------------------------------------------------- | ----------------------------- |
| **SIGNOZ\_URL**      | URL cơ sở của instance, không có hậu tố path                         | `https://<hash>.signoz.cloud` |
| **SIGNOZ\_API\_KEY** | Service Account key                                                  | Sao chép từ tab Keys          |
| **LOG\_LEVEL**       | Độ chi tiết log của MCP server: `debug`, `info`, `warn` hoặc `error` | `info`                        |

***

## Quyền yêu cầu

* **`signoz-viewer`** cấp quyền truy cập chỉ đọc: truy vấn dịch vụ, log, trace, số liệu và kiểm tra cảnh báo, dashboard và view.
* **`signoz-admin`** bổ sung quyền ghi: tạo, cập nhật hoặc xóa cảnh báo, dashboard, view và channel.
* Các thao tác ghi cũng yêu cầu [phê duyệt](/vi/guide/approval) rõ ràng trong CloudThinker trước khi thực thi.

<Tip>
  Bắt đầu với `signoz-viewer` để điều tra chỉ đọc. Chỉ gán `signoz-admin` khi bạn muốn agent quản lý cảnh báo hoặc dashboard.
</Tip>

***

## Khả năng của agent

Sau khi kết nối, các agent có thể thực hiện các thao tác đọc trên dữ liệu quan sát của bạn và một tập hợp các thao tác ghi được kiểm soát bởi phê duyệt.

| Khả năng           | Chức năng của agent                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| **Dịch vụ (APM)**  | Liệt kê các dịch vụ được đo đạc, kiểm tra các thao tác hàng đầu theo độ trễ                                     |
| **Log**            | Tìm kiếm log theo thời gian và bộ lọc, tổng hợp và nhóm theo mẫu                                                |
| **Trace**          | Tìm kiếm trace, lấy toàn bộ waterfall trace, đi sâu vào các phụ thuộc                                           |
| **Số liệu**        | Liệt kê số liệu và chạy truy vấn time-series                                                                    |
| **Dashboard**      | Liệt kê và kiểm tra dashboard và template                                                                       |
| **Cảnh báo**       | Liệt kê quy tắc cảnh báo, kiểm tra quy tắc và lịch sử chuyển đổi trạng thái; tạo, cập nhật hoặc xóa (chỉ admin) |
| **View đã lưu**    | Liệt kê, kiểm tra, tạo, cập nhật hoặc xóa view truy vấn đã lưu (chỉ admin)                                      |
| **Kênh thông báo** | Liệt kê, kiểm tra, tạo, cập nhật hoặc xóa channel (chỉ admin)                                                   |
| **Tài liệu**       | Tìm kiếm và lấy tài liệu SigNoz                                                                                 |

<Warning>
  Các thao tác ghi thay đổi cảnh báo và dashboard trực tiếp. CloudThinker yêu cầu [phê duyệt](/vi/guide/approval) rõ ràng, nêu tên tài nguyên, trước khi bất kỳ thao tác ghi nào được thực thi. Các thao tác xóa không thể hoàn tác.
</Warning>

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

```text theme={null}
@tony list SigNoz services and confirm that metrics and traces are reachable
```

### Ví dụ lệnh

```text theme={null}
@tony find the slowest operations for the checkout service
@tony search error logs and group spikes by service
@tony audit SigNoz alert rules and flag misconfigured thresholds
```

***

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

<Accordion title="Kết nối thất bại với 401 Unauthorized">
  Xác minh API key đúng và chưa bị thu hồi. Xác nhận bạn đã nhấn **Save Changes** sau khi gán vai trò, rồi tạo lại key.
</Accordion>

<Accordion title="Mọi yêu cầu đều trả về 404">
  `SIGNOZ_URL` có hậu tố path thừa. Đặt thành URL cơ sở, ví dụ `https://<hash>.signoz.cloud`, không có `/api/v1`.
</Accordion>

<Accordion title="403 Forbidden">
  Vai trò của service account quá thấp cho thao tác yêu cầu. Gán `signoz-admin` cho các thao tác ghi, rồi nhấn **Save Changes**.
</Accordion>

<Accordion title="Tìm kiếm không trả về kết quả">
  Tìm kiếm log, trace và số liệu cần khoảng thời gian. Yêu cầu agent dùng cửa sổ gần đây (ví dụ 15 phút qua) và mở rộng chỉ khi cần.
</Accordion>

***

## 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.

- **Chỉ URL cơ sở** — đặt `SIGNOZ_URL` thành URL gốc không có hậu tố path; đường dẫn thừa khiến mọi yêu cầu trả về 404.
- **Phê duyệt cho các thao tác ghi** — giữ các thao tác ghi được kiểm soát bởi phê duyệt để các thay đổi cảnh báo và dashboard luôn có chủ ý.

***

## Liên quan

<CardGroup cols={2}>
  <Card title="Kết nối Datadog" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/datadog.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=e8382167f2a1eb1e00971b5f4d703d48" href="/vi/guide/connections/datadog" width="24" height="24" data-path="images/icons/datadog.svg">
    Quan sát và giám sát
  </Card>

  <Card title="Kết nối Grafana" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/grafana.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=c1329049025cd3c3a0909b400baef7be" href="/vi/guide/connections/grafana" width="24" height="24" data-path="images/icons/grafana.svg">
    Dashboard và số liệu
  </Card>
</CardGroup>