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

# PostHog

> Kết nối PostHog để CloudThinker có thể phân loại lỗi được theo dõi, đọc flag và insight, và trả lời câu hỏi về mức sử dụng bằng HogQL

Kết nối một project PostHog để [CloudThinker](https://docs.cloudthinker.io/vi/guide/agents/overview.md) có thể xếp hạng các lỗi ảnh hưởng đến người dùng, báo cáo về feature flag, insight, dashboard và survey, và trả lời câu hỏi về mức sử dụng bằng HogQL (ngôn ngữ truy vấn giống SQL của PostHog). Kết nối dùng personal API key của PostHog, và các scope của key quyết định CloudThinker có thể truy cập những gì.

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

* Một tài khoản PostHog Cloud (US hoặc EU) có quyền truy cập vào project bạn muốn CloudThinker đọc. PostHog tự host không được hỗ trợ: kết nối chỉ truy cập được cloud US và EU của PostHog.
* Quyền tạo personal API key trong tài khoản đó.
* Một project đang nhận event. Project không có event nào sẽ cho câu trả lời trống, không phải kết nối bị lỗi.

## Thiết lập

**1. Tạo personal API key trong PostHog**

Trong PostHog, mở cài đặt tài khoản (personal API key thuộc về người dùng của bạn, không nằm trong cài đặt project), vào **Personal API keys** và nhấn **+ Create a personal API Key**. Đặt nhãn là `CloudThinker`.

**2. Chọn preset MCP Server**

Chọn preset **MCP Server**. Preset này giới hạn key trong một project. Trước khi tạo key, hãy xem lại các scope mà preset chọn, và bỏ chọn mọi scope ghi mà bạn không muốn CloudThinker có. Nếu tự chọn scope, chỉ chọn các mục trong [Quyền yêu cầu](#quyền-yêu-cầu).

**3. Sao chép key**

Sao chép giá trị key (bắt đầu bằng `phx_`). PostHog chỉ hiển thị một lần và ẩn đi sau khi bạn tải lại trang.

**4. Kết nối trong CloudThinker**

Trên thanh bên, nhấn **More → Workspace settings → Connections**, giữ nguyên tab **Builtin Connections** và chọn **PostHog**. Dán key vào **POSTHOG\_PERSONAL\_API\_KEY**, chọn **POSTHOG\_REGION** và nhấn **Connect**. CloudThinker kiểm tra kết nối bằng cách mở một phiên với MCP server của PostHog cho region đó.

**Trạng thái thành công:** kết nối PostHog hiển thị trạng thái **Connected**. Chạy prompt xác minh bên dưới để xác nhận key đọc được project của bạn.

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

> [!WARNING]
>
> Prompt PostHog đầu tiên của bạn có thể dừng lại chờ phê duyệt, dù chỉ đọc. CloudThinker coi mọi lệnh gọi PostHog là thao tác ghi. Xem [Quyền ghi](#quyền-ghi).

```text theme={null}
Show my PostHog organization, the active project, and how many feature flags and insights it has
```

**Trạng thái thành công:** CloudThinker nêu tên tổ chức và project đang hoạt động, đồng thời liệt kê flag, insight, dashboard, survey và lỗi được theo dõi của project. Project không có flag hay insight nào trả về danh sách trống, không phải lỗi. Lỗi key không hợp lệ có nghĩa là key hoặc region sai; xem [Khắc phục sự cố](#khắc-phục-sự-cố).

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

| Trường | Nội dung cần nhập |
| - | - |
| **Alias** | Tên ngắn cho kết nối này, như `web-app`. Agent và [Rule](https://docs.cloudthinker.io/vi/guide/approvals/rules.md) dùng tên này để phân biệt các kết nối |
| **Description** | Project của kết nối này bao gồm những gì, như `Product analytics for the web app`. Agent đọc mô tả để chọn đúng kết nối |
| **POSTHOG\_PERSONAL\_API\_KEY** | Personal API key bạn đã tạo, bắt đầu bằng `phx_` |
| **POSTHOG\_REGION** | Chọn **US** nếu bạn đăng nhập tại `us.posthog.com`, hoặc **EU** nếu đăng nhập tại `eu.posthog.com`. Các tùy chọn cũng hiển thị địa chỉ máy chủ PostHog cho region đó. Mặc định là US. |

Mỗi key chỉ thuộc về một cloud PostHog. Nếu gửi sang region còn lại, key sẽ bị từ chối với lỗi key không hợp lệ. Mỗi kết nối làm việc với một project đang hoạt động; để bao phủ project thứ hai, hãy thêm kết nối PostHog thứ hai với key riêng.

## Quyền yêu cầu

Personal API key mang các scope theo từng tài nguyên, chẳng hạn `insight:read`. CloudThinker không thể truy cập bất cứ thứ gì nằm ngoài các scope.

| Khu vực | Lý do CloudThinker cần |
| - | - |
| **Organizations and projects** | Nêu tên tổ chức và xác nhận project đang hoạt động |
| **Feature flags** | Báo cáo những flag nào tồn tại, mức rollout và trạng thái |
| **Insights and dashboards** | Đọc các insight đã lưu và các dashboard chứa chúng |
| **Surveys** | Báo cáo những survey nào đang chạy và chúng hỏi gì |
| **Error tracking** | Xếp hạng issue, nhóm theo trạng thái và mở chi tiết issue |
| **Query** | Chạy HogQL và đọc event schema |

> [!TIP]
>
> Bắt đầu chỉ với scope đọc. Chỉ thêm scope ghi, ví dụ cho feature flag, nếu bạn muốn CloudThinker đề xuất thay đổi ở đó.

## Khả năng của agent

| Khả năng | CloudThinker làm gì |
| - | - |
| **Project discovery** | Nêu tên tổ chức và project đang hoạt động, rồi liệt kê flag, insight, dashboard, survey và lỗi được theo dõi |
| **Error triage** | Xếp hạng issue lỗi theo số lần xảy ra, nhóm theo trạng thái và mở những issue nghiêm trọng nhất |
| **Usage trends** | Tóm tắt khối lượng event trong một khoảng thời gian (tối đa 90 ngày) và nêu các event hàng đầu |
| **Event schema** | Báo cáo những event và property mà project thực sự ghi nhận, trước khi truy vấn chúng |
| **HogQL queries** | Trả lời câu hỏi bằng một truy vấn có giới hạn số dòng riêng |
| **Changes** | Tạo hoặc cập nhật feature flag, insight, dashboard, experiment, survey, annotation, cohort hoặc alert. Mỗi thay đổi đi qua Approvals của bạn, và người phê duyệt thấy chính xác dữ liệu đầu vào trước |

## Ví dụ prompt

```text theme={null}
Which PostHog errors are hurting the most users right now?
Show signup event volume for the last 7 days
Which feature flags are rolled out to more than half of users?
```

## Quyền ghi

PostHog cung cấp toàn bộ công cụ thông qua một công cụ lệnh duy nhất, và công cụ đó có thể thực hiện mọi thay đổi mà PostHog cho phép. Vì vậy CloudThinker coi mọi lệnh gọi PostHog là thao tác ghi, kể cả lệnh chỉ đọc.

Mọi thay đổi do agent thực hiện đều đi qua [Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md) của workspace trước. Ở chế độ mặc định **Auto · Rules + AI · Ask me**, AI judgment có thể cho một thay đổi an toàn chạy mà không cần hỏi. Allow Rule cũng vậy, sau khi CloudThinker bật [Rule enforcement](https://docs.cloudthinker.io/vi/guide/approvals/rules.md#khắc-phục-sự-cố) cho workspace của bạn. Chọn **Manual** nếu bạn muốn tự phê duyệt mọi thay đổi.

Chọn **Manual** để có người phê duyệt mọi lệnh gọi PostHog, dù đọc hay ghi. Vì PostHog chỉ có một công cụ lệnh, không Rule nào có thể phân biệt lệnh đọc với lệnh ghi của PostHog — nên khi CloudThinker bật [Rule enforcement](https://docs.cloudthinker.io/vi/guide/approvals/rules.md#khắc-phục-sự-cố) cho workspace của bạn, một Rule **Allow** cho các lệnh gọi PostHog cũng sẽ cho phép cả thay đổi feature flag.

> [!WARNING]
>
> Thay đổi feature flag ảnh hưởng đến người dùng thật ngay khi chạy, còn chuyển project đang hoạt động sẽ đổi project mà phần còn lại của cuộc hội thoại đọc. Hãy kiểm tra chính xác dữ liệu đầu vào trong lời nhắc phê duyệt trước khi phê duyệt.

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

> **Mọi lệnh gọi đều thất bại với lỗi key không hợp lệ**
>
> Key đến từ cloud PostHog còn lại, hoặc đã bị thu hồi. Đặt **POSTHOG\_REGION** khớp với host bạn đăng nhập. Nếu đã đúng, hãy tạo key mới và cập nhật kết nối.

> **CloudThinker báo một khả năng không khả dụng, hoặc project có vẻ trống**
>
> Key thiếu scope đó. PostHog ẩn các công cụ mà key không truy cập được, nên trông có thể giống một project không có flag hoặc lỗi nào. Mở key trong PostHog, thêm scope hoặc tạo key mới với preset **MCP Server**, rồi cập nhật kết nối.

> **CloudThinker đọc sai project**
>
> Mỗi kết nối chỉ có một project đang hoạt động. Hỏi `Which PostHog project is active?` để kiểm tra. Để thay đổi, hãy yêu cầu CloudThinker chuyển project: thao tác chuyển sẽ hiển thị thành lời nhắc phê duyệt. Hoặc thêm kết nối PostHog thứ hai với key cho project kia.

> **Lệnh đọc dừng lại chờ phê duyệt**
>
> Đây là hành vi mong đợi. CloudThinker coi mọi lệnh gọi PostHog là thao tác ghi, nên lệnh đọc cũng có thể dừng lại. Xem [Quyền ghi](#quyền-ghi) để biết mỗi chế độ Approval xử lý lệnh gọi PostHog thế nào.

> **Lệnh gọi thất bại với 429 sau khi dùng nhiều**
>
> PostHog trả về lỗi giới hạn tốc độ 429. Giới hạn tốc độ của PostHog được chia sẻ giữa mọi người dùng và key trong tổ chức của bạn. Chờ giới hạn được đặt lại, rồi hỏi một câu hẹp hơn để CloudThinker đọc ít hơn.

> **Tôi đã làm mất giá trị key**
>
> PostHog chỉ hiển thị personal API key một lần. Tạo key mới và cập nhật kết nối.

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

- **Bảo vệ key như mật khẩu**: personal API key có thể hành động như người dùng PostHog của bạn trong phạm vi các scope của key. Dùng preset **MCP Server** và chỉ dùng key cho CloudThinker, để bạn có thể thu hồi riêng key đó.
- **Project token không xuất hiện trong chat**: CloudThinker đọc chi tiết project qua một đường đi loại bỏ ingestion token của project, nên token không bao giờ xuất hiện trong cuộc hội thoại.

## Liên quan

> **[Kết nối Sentry](https://docs.cloudthinker.io/vi/guide/connections/sentry.md)**
>
> Điều tra lỗi và hiệu năng ứng dụng trong Sentry

> **[Approvals](https://docs.cloudthinker.io/vi/guide/approvals/overview.md)**
>
> Quyết định những thao tác ghi nào của kết nối được chạy mà không cần hỏi bạn


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