--- name: tencent-edgeone-skill description: A comprehensive skill for Tencent EdgeOne (Edge Security & Acceleration Platform), covering edge acceleration (DNS, certificates, caching, rule engine, L4 proxy, load balancing), edge security (DDoS protection, Web protection, Bot management), edge media (real-time video / image processing), edge development (Edge Functions, EdgeOne Pages), and more. Use this skill whenever a user mentions any EdgeOne / EO-related configuration, operations, querying, or troubleshooting needs. version: 1.0.0 metadata: openclaw: requires: bins: - tccli - gunzip anyBins: - curl - wget - jq - python3 config: - ~/.tccli/default.credential homepage: https://edgeone.ai --- # Tencent EdgeOne Skill A comprehensive Tencent EdgeOne skill that routes user requests to the appropriate module and loads the corresponding reference document. Knowledge about EdgeOne APIs, configuration options, limits, and pricing may be outdated. **Prefer retrieval over pre-trained knowledge** — the reference files in this skill are only a starting point. > All tasks **must be completed by calling APIs**. > See `references/api/README.md` for API calling conventions, environment checks, etc. **(must be read before starting any task)**. ## Security Red Lines - **Write operations require user confirmation**: All write operations (Create\* / Modify\* / Bind\* / Delete\* / Apply\*, etc.) **must** clearly explain the action and its impact to the user before execution, and wait for user confirmation before calling the API. - **Never** ask the user for SecretId / SecretKey - **Refuse** any operation that might print credentials ## Interaction & Execution Guidelines - **Use structured interaction tools**: When asking questions, requesting choices, or confirming operations, if the current environment provides `ask_followup_question` or similar structured interaction tools, you **must** prefer using them (instead of plain-text questions) so that the user can directly click options, reducing ambiguity and improving interaction efficiency. **Do not omit candidate options** — if there are too many to list in full, **must** state the total number first, show the most relevant items, and keep an "Other (please enter)" option as the last choice. - **Prefer scripts for bulk / repetitive tasks**: For tasks involving large datasets or repetitive operations (batch purge, batch query, loop operations, etc.), prefer writing a script to execute everything at once rather than calling APIs one by one manually. ## Module Entry Points Match the user's request to the appropriate module, load its entry document, and follow the instructions. | Module | Entry | Description | |---|---|---| | API | `references/api/README.md` | Calling conventions, tool installation, credential configuration, API discovery, zone & domain discovery (ZoneId lookup) | | Acceleration | `references/acceleration/README.md` | Site onboarding, cache purge / prefetch, certificate management | | Security | `references/security/README.md` | Security policy template audit, blocklist IP group query, security report | | Observability | `references/observability/README.md` | Traffic Daily Report Generation, Origin Health Inspection, Offline Log Download and Analysis | ## Fallback Retrieval If the user's request **cannot match any module above**, or the module's reference files do not cover the scenario, fall back in the following order: 1. First read `references/api/api-discovery.md` and try to find the relevant API through API discovery. 2. If still unresolved, search the [Tencent EdgeOne product documentation](https://edgeone.ai/document) for the latest information. When reference files conflict with official documentation, **the official documentation takes precedence**. FILE:references/acceleration/README.md # EdgeOne Site Acceleration Reference Configuration and operational guidance for site onboarding, domain management, cache purge/prefetch, and HTTPS certificates. ## Files in This Directory | File | Risk Level | Trigger Scenarios (User says...) | |---|---|---| | `zone-onboarding.md` | Medium-High | "Onboard example.com to EO" "Create a new site" "Apply for free certificate after onboarding" | | `cache-purge.md` | Medium | "Purge all cache under /static/" "Prefetch these URLs" "Check purge task status" | | `cert-manager.md` | Medium | "Renew certificate that's expiring soon" "Bind new certificate to these domains" "Check certificate status" | FILE:references/acceleration/cache-purge.md # Cache Purge and Prefetch Manage EdgeOne node cache: query quotas, purge cache (URL / Directory / Host / All / Cache Tag), prefetch URLs, and check task progress. Supports batch URL input from files or paste. ## Core Interaction Guidelines 1. **Site Selection and Confirmation**: Before executing any cache operation, users must first confirm the target site (see Scenario 0) 2. **Check Quota Before Submission**: Before executing CreatePurgeTask / CreatePrefetchTask, call DescribeContentQuota to display remaining quota; warn users if insufficient 3. **Batch URL Input**: Support users to input URLs in batch from files or by pasting (see Scenario E) 4. **Poll Task Progress**: Actively query progress after task submission until completion or timeout ## Scenario 0: Select Site **Trigger**: Before users request cache purge or URL prefetch, the target site must be confirmed first. **Steps**: 1. **Call DescribeZones to query site list** - **Important**: Filter out sites with `Status` as `initializing` (these sites are still initializing and haven't completed creation) - **Critical**: **Must use pagination** to retrieve all sites: - Set `Limit=100` (maximum value) - Set `Offset=0` initially, increment by 100 each iteration - Loop until `Offset + Limit >= TotalCount` - Merge all paginated results - Refer to [zone-discovery.md](../api/zone-discovery.md) for detailed pagination implementation - Only display available sites 2. **Determine the number of sites**: **a) Only one site** - Directly use this site without user selection - Continue to subsequent operations **b) Multiple sites** - List all available sites, including: - Site domain name (ZoneName) - Alias Zone Name (AliasZoneName, if any) - Site ID (ZoneId) - Access mode (Type) - Guide users to select the site to operate on **c) No available sites** - Prompt user: "No available sites under current account, please create a site first" - Terminate operation 3. **Handle sites with same name**: - If multiple sites with the same name exist (same ZoneName), they must be distinguished by `AliasZoneName` (Alias Zone Name identifier) - Display format: `Site domain (identifier)` or `Site domain [identifier]` - Example: `example.com (prod)` and `example.com (test)` 4. **Get Site ID**: - After user confirms the site, record the site's `ZoneId` - All subsequent API calls use this `ZoneId` > **Important Notes**: > - Site selection is a prerequisite for all cache operations and cannot be skipped > - Alias Zone Name (AliasZoneName) is used to distinguish sites with the same name created with different access modes (CNAME, DNSPod hosting) > - If the user explicitly specifies the site domain or identifier in the request, you can directly use this information to query the corresponding site ## Scenario A: Query Quota **Trigger**: User says "how many more can I purge", "check quota", "how much prefetch quota left". > **Prerequisite** (optional): If user hasn't specified a site, complete [Scenario 0: Select Site](#scenario-0-select-site) first Call `DescribeContentQuota`, passing parameters: - `ZoneId`: Site ID (optional, query account-level quota if not provided) **Output suggestion**: Display quota usage for each type in a table, marking types with less than 10% remaining. ## Scenario B: Cache Purge **Trigger**: User says "purge cache", "clear CDN cache", "purge URL", "purge directory", "purge entire site". > **Prerequisites**: > 1. Complete [Scenario 0: Select Site](#scenario-0-select-site) to confirm the site to operate on > 2. Call DescribeAccelerationDomains to confirm available acceleration domains under the site > 3. Call DescribeContentQuota (Scenario A) to display remaining quota; warn user if insufficient for the corresponding type ### B1: Confirm Purge Type and Method Before executing purge, **must** have users confirm the following information: #### 1. Purge Type | Type | Parameter Value | Description | Impact Scope | |------|--------|------|----------| | **URL Purge** | `purge_url` | Purge specified URLs | Exactly matched URLs | | **Directory Purge** | `purge_prefix` | Purge all resources under specified directory | All files under directory and subdirectories | | **Hostname Purge** | `purge_host` | Purge all resources under specified domain | All cache of the entire acceleration domain | | **Full Site Purge** | `purge_all` | Purge all resources under the site | ⚠️ All cache on all nodes of the site | | **Cache Tag Purge** | `purge_cache_tag` | Purge by cache tag | All cache with specified tags | #### 2. Purge Method Purge method is **only valid for the following three purge types**: - ✅ **Directory Purge** (`purge_prefix`) - ✅ **Hostname Purge** (`purge_host`) - ✅ **Full Site Purge** (`purge_all`) Other purge types (URL purge, Cache Tag purge) do not support the purge method parameter. **Available Values**: | Method | Parameter Value | Description | Recommended Scenario | |------|--------|------|----------| | **Invalidate Cache** | `invalidate` | Mark cache as expired, validate with origin on next request | Default method, less pressure on origin | | **Delete Cache** | `delete` | Directly delete cache, always fetch from origin on next request | Emergency updates, forced refresh scenarios | > **Important Notes**: > - The `invalidate` method keeps the cache but marks it as expired; on the next request, it validates with the origin through mechanisms like If-Modified-Since, and can continue using cache if content hasn't changed > - The `delete` method directly deletes the cache; all subsequent requests will fetch from origin, which will increase origin load in a short time #### 3. User Confirmation Process **Prompt user**: 1. Display purge types and their impact scope 2. If selecting `purge_prefix`, `purge_host`, or `purge_all`, ask about purge method 3. If selecting `purge_all` (full site purge), **must** specially warn: > ⚠️ **Full site purge is a high-impact operation**: It will clear all node cache of this site; in a short time, a large number of requests will fetch from origin, which may cause origin pressure to surge. Please confirm whether to continue? 4. Wait for user's explicit confirmation before executing > **No automatic purge**: Cache purge will invalidate node cache; subsequent requests will fetch the latest content from origin, which may increase origin load. **Must** explain the purge type and impact scope to users and wait for explicit confirmation before execution. ### B2: Execute Purge **Call** `CreatePurgeTask`, passing parameters: - `ZoneId`: Site ID (from Scenario 0) - `Type`: Purge type - `Method`: Purge method (only valid when Type is `purge_prefix`, `purge_host`, or `purge_all`) - `Targets`: List of URLs / directories / domains to purge **Follow-up**: Inform user that the task has been submitted and provide JobId. If confirmation of execution result is needed, go to [Scenario D](#scenario-d-query-task-progress). ## Scenario C: URL Prefetch **Trigger**: User says "prefetch URL", "prefetch cache", "prefetch", "preload resources". > **Prerequisites**: > 1. Complete [Scenario 0: Select Site](#scenario-0-select-site) to confirm the site to operate on > 2. Call DescribeContentQuota (Scenario A) to display remaining `prefetch_url` quota > 3. (Optional) Call DescribePrefetchOriginLimit to query origin rate limit for the target domain URL prefetch actively fetches resources from origin to edge node cache, suitable for preloading hot resources before major promotions or version releases. ### C1: URL Format Check Before executing prefetch, **must** check if URL format meets requirements: **✅ Supported URL Formats**: - Complete HTTP/HTTPS URL: `https://example.com/path/to/file.jpg` - URL with query parameters: `https://example.com/api/data?id=123&type=json` - Specific file path: `https://cdn.example.com/images/banner.png` **❌ Unsupported URL Formats**: - ⚠️ **URLs with wildcards**: `https://example.com/path/*` or `https://example.com/*.jpg` - Directory paths: `https://example.com/path/` (for directory prefetch, use multiple specific file URLs) - Incomplete URLs: `example.com/path` (missing protocol) **Check Rules**: 1. URL must start with `http://` or `https://` 2. URL cannot contain wildcards `*` or `?` (except `?` in query parameters) 3. It's recommended that each URL points to a specific file resource **Processing Flow**: ``` Iterate through user-provided URL list ├─ Check if contains wildcards (* ?) │ ├─ Contains → Prompt user: "Prefetch doesn't support wildcard URLs, please provide specific file URLs" │ └─ Doesn't contain → Continue ├─ Check protocol │ ├─ Missing http/https → Prompt user to add protocol │ └─ Has protocol → Continue └─ Add to valid URL list ``` > **Important Notes**: > - Prefetch only supports URL granularity, not directory or domain level > - To prefetch an entire directory, you need to provide a complete URL list of all files under that directory > - Wildcard purge is partially supported in cache purge scenarios (such as directory purge), but not supported in prefetch scenarios ### C2: Execute Prefetch **Call** `CreatePrefetchTask`, passing parameters: - `ZoneId`: Site ID (from Scenario 0) - `Targets`: List of URLs to prefetch (passed format check) **Follow-up**: Inform user that the task has been submitted and provide JobId. If confirmation of execution result is needed, go to [Scenario D](#scenario-d-query-task-progress). ### C3: Query Prefetch Origin Rate Limit (DescribePrefetchOriginLimit) > This interface is a whitelist beta feature, only use when user mentions "prefetch rate limit". Call `DescribePrefetchOriginLimit`. **Output suggestion**: If the domain has rate limit configuration, remind the user of the current bandwidth limit before prefetching; large-scale prefetch may be affected by this limit. ## Scenario D: Query Task Progress **Trigger**: User says "is purge done", "check task progress", "prefetch status". ### D1: Query Purge Tasks Call `DescribePurgeTasks`. ### D2: Query Prefetch Tasks Call `DescribePrefetchTasks`, parameters and Filters similar to purge tasks. **Output suggestion**: Display task list in a table, marking tasks with `failed` and `timeout` status. If there are failed tasks, suggest users to check if URLs are correct or retry later. > Prefetch tasks additionally have `invalid` status, indicating origin response is non-2xx; need to check origin service. ### D3: Auto-poll Progress After Submission After submitting purge / prefetch tasks, should actively poll task status until terminal state: 1. Get `JobId` after submitting task 2. Wait 5-10 seconds before querying status 3. If still `processing`, continue waiting and retry (suggest 10-second interval) 4. If reaching terminal state (`success` / `failed` / `timeout` / `canceled`), summarize results and display to user > Usually URL purge completes in 1-2 minutes, directory / Host purge in 3-5 minutes; prefetch time depends on resource size and quantity. ## Scenario E: Batch URL Input **Trigger**: User provides a large number of URLs (read from file or directly paste multiple lines). ### E1: Extract URLs from User's Pasted Text When user pastes multiple lines of URLs: 1. Split text by lines, one URL per line 2. Filter out empty lines and comment lines (starting with `#`) 3. Ensure each URL starts with `http://` or `https://` 4. Summarize valid URL count and display to user for confirmation ### E2: Read URL List from File When user says "import from file", "read URL list file": 1. Read user-specified file (support `.txt`, `.csv` and other plain text formats) 2. Parse by lines, filter empty lines and comments 3. Display parsed URL count and first few samples, ask user to confirm ### E3: Batch Submission Considerations - **Check Quota**: First query DescribeContentQuota to ensure remaining quota ≥ URL count - **Single Batch Limit**: Number of URLs submitted each time is subject to single batch upper limit; automatically submit in batches when exceeding limit - **URL Deduplication**: Deduplicate before submission to avoid wasting quota - **Result Summary**: After all batches are submitted, summarize JobId list and failed items, query progress uniformly FILE:references/acceleration/cert-manager.md # Certificate Automation Management Manage EdgeOne domain HTTPS certificates: query certificate status, apply for free certificates, deploy custom certificates. ## Scenario A: Query Certificate Status **Trigger**: User wants to view certificate list or check expiration time. ### A1: Locate Target Site Call `DescribeZones`, using `zone-name` filter to match the site name specified by the user. > **Important**: Filter out sites with `Status` as `initializing` (these sites are still initializing and haven't completed creation). Handle based on results in three cases: **Case 1: Only 1 available site matched** Directly use this site's `ZoneId`, proceed to A2. **Case 2: Multiple sites with same name matched** Display all **available** matching results to user, listing key information for distinction, **wait for user's explicit selection** before continuing: ``` Found multiple sites named "xxx.com", please confirm which one to query: 1. ZoneId: zone-aaa Alias: prod Access Mode: NS Access Created: 2024-01-01 2. ZoneId: zone-bbb Alias: test Access Mode: CNAME Access Created: 2025-06-01 Please reply with the number or ZoneId. ``` > After receiving user's response, use the selected `ZoneId` to proceed to A2. **Case 3: No available sites** Prompt user: "No available site 'xxx.com' found, please check the site name or wait for site initialization to complete." ### A2: Query Domain Certificate Information Call `DescribeAccelerationDomains`, read certificate information for each domain from the `AccelerationDomains[].Certificate` field in the response. > You can specify a domain to query via `Filters.domain-name`; not passing Filters returns all domains under the site. Key fields in each domain's `Certificate` structure: | Field | Meaning | |---|---| | `Certificate.Mode` | Certificate configuration mode: `disable` / `eofreecert` / `eofreecert_manual` / `sslcert` | | `Certificate.List[].CertId` | Certificate ID | | `Certificate.List[].Alias` | Certificate alias | | `Certificate.List[].Type` | Certificate type: `default` / `upload` / `managed` | | `Certificate.List[].ExpireTime` | Expiration time | | `Certificate.List[].Status` | Deployment status: `deployed` / `processing` / `applying` / `failed` / `issued` | | `Certificate.List[].SignAlgo` | Signature algorithm | **Output suggestion**: Display certificate information for each domain in table format, marking entries that are about to expire (≤30 days) or have abnormal status (`failed` / `applying`). ## Scenario B: Apply and Deploy Free Certificate **Trigger**: User says "apply for free certificate", "certificate is expiring soon", "renew certificate". ### B0: Locate Target Site If user hasn't directly provided ZoneId, call `DescribeZones` using `zone-name` filter to match the site name specified by the user. > **Important**: Filter out sites with `Status` as `initializing` (these sites are still initializing and haven't completed creation). - **Only 1 available site matched**: Directly use this site's `ZoneId`, proceed to B1. - **Multiple sites with same name matched**: Display all **available** matching results to user, **wait for explicit selection** before continuing (display format same as Scenario A). - **No available sites**: Prompt user: "No available site 'xxx.com' found, please check the site name or wait for site initialization to complete." ### Access Mode Determination The result of calling `DescribeZones` is also used to determine the access mode (`Type` field), taking different routes based on the result: | Access Mode | Free Certificate Application Method | |---|---| | NS Access / DNSPod Hosting | **Automatic Validation** — Directly call ModifyHostsCertificate | | CNAME Access | **Manual Validation** — Need to call ApplyFreeCertificate first, complete validation, then deploy | ### B1: NS Access / DNSPod Hosting (Automatic Validation) Call `ModifyHostsCertificate`. > **Confirmation Prompt**: Deploying certificate will affect the domain's HTTPS service, need user confirmation before execution. ### B2: CNAME Access (Manual Validation) Requires 4 steps: **Step 1**: Call `ApplyFreeCertificate` to initiate application. **Step 2**: Based on validation information in response, inform user to complete configuration. > After informing user, **wait for user to confirm configuration completion** before continuing to next step. **Step 3**: Call `CheckFreeCertificateVerification` to check validation result - Success: Response contains certificate information, indicating certificate has been issued - Failure: Need to check if validation configuration is correct **Step 4**: Call `ModifyHostsCertificate` to deploy free certificate. > **Confirmation Prompt**: Deploying certificate will affect the domain's HTTPS service, need user confirmation before execution. ## Scenario C: Deploy Custom Certificate **Trigger**: User says "configure custom certificate", "uploaded certificate", or provides CertId. ### C0: Locate Target Site If user hasn't directly provided ZoneId, call `DescribeZones` using `zone-name` filter to match the site name specified by the user. > **Important**: Filter out sites with `Status` as `initializing` (these sites are still initializing and haven't completed creation). - **Only 1 available site matched**: Directly use this site's `ZoneId`, proceed to next step. - **Multiple sites with same name matched**: Display all **available** matching results to user, **wait for explicit selection** before continuing (display format same as Scenario A). - **No available sites**: Prompt user: "No available site 'xxx.com' found, please check the site name or wait for site initialization to complete." ### C1: Query SSL Certificates Applicable to Target Domain If user hasn't provided CertId, or wants to select from existing certificates, call `ssl:DescribeCertificates` to query certificate list, then filter out certificates applicable to the target domain. **Call Parameter Suggestions**: - `SearchKey`: Pass in target domain (e.g., `a-1.qcdntest.com`), can fuzzy match domain field to narrow return range - `CertificateType`: Pass `SVR`, only query server certificates (exclude client CA certificates) - `Limit`: Suggest passing `1000` to ensure no omissions **Filter Rules**: For each returned certificate, check if any entry in the `SubjectAltName` list matches the target domain: | Match Type | Description | Example | |---|---|---| | Exact Match | `SubjectAltName` has an entry exactly the same as target domain | `a-1.qcdntest.com` | | Wildcard Match | `SubjectAltName` has a `*.xxx` entry, and target domain is its direct subdomain (only one level) | `*.qcdntest.com` matches `a-1.qcdntest.com` | **Availability Determination**: After filtering matching certificates, mark availability status for each certificate based on the following fields: | Field | Meaning | Availability Condition | |---|---|---| | `Status` | Certificate status | Must be `1` (Approved) | | `CertEndTime` | Expiration time | Days until today > 0 (Not expired) | | `Deployable` | Whether deployable | Must be `true` | **Output suggestion**: Display all matching certificates in a table, marking availability: ``` Certificates applicable to a-1.qcdntest.com: Cert ID Alias Expiration Days Left Status Deployable Availability ------------ -------------- -------------------- ---------- ---------- ----------- ------------ zVq87w0D my-cert 2032-09-23 05:10:56 2371 days Approved ✅ ✅ Available QxbtGBIM old-cert 2025-01-01 00:00:00 -86 days Expired ❌ ❌ Expired ``` If no matching certificate is found, inform user that they need to first go to [SSL Certificate Console](https://console.cloud.tencent.com/ssl) to upload or apply for a certificate covering this domain. ### C2: Deploy Certificate After user selects certificate from C1 results, call `ModifyHostsCertificate` (`Mode=sslcert`, `ServerCertInfo[{CertId}]`). > **No Automatic Deployment**: **Must** confirm deployment domain and certificate ID with user before execution. ## Scenario D: Batch Certificate Inspection **Trigger**: User says "check certificates for all domains", "which certificates are expiring soon". ### Process 1. Call `DescribeZones` to get all sites - **Important**: Filter out sites with `Status` as `initializing` (these sites are still initializing and haven't completed creation) - **Critical**: **Must use pagination** to retrieve all sites: - Set `Limit=100` (maximum value) - Set `Offset=0` initially, increment by 100 each iteration - Loop until `Offset + Limit >= TotalCount` - Merge all paginated results - Refer to [zone-discovery.md](../api/zone-discovery.md) for detailed pagination implementation 2. Call `DescribeAccelerationDomains` for each **available** site, read certificate information from each `AccelerationDomains[].Certificate` field in the response 3. Summarize output, marking the following anomalies: - Certificates with `Certificate.List[].Status` as `failed` or `applying` - Certificates with `Certificate.List[].ExpireTime` ≤30 days from today - Domains with `Certificate.Mode` as `disable` or `Certificate` is null (no certificate configured) ### Output Format Suggestion ```markdown ## Certificate Inspection Report | Site | Domain | Cert ID | Expiration | Days Left | Status | |---|---|---|---|---|---| | example.com | *.example.com | teo-xxx | 2026-04-15 | 29 days | Expiring Soon | | example.com | api.example.com | teo-yyy | 2026-09-01 | 168 days | Normal | ``` FILE:references/acceleration/zone-onboarding.md # Site One-Click Onboarding Guide End-to-end domain onboarding to EdgeOne: confirm plan → create site → verify ownership → add acceleration domain → apply and deploy certificate. ## Important Concepts ### Alias Zone Name (AliasZoneName) When you create two or more sites with the same site name, you need to use an **Alias Zone Name** to distinguish them. **Use Cases**: - Same domain using different access modes (CNAME access, DNSPod hosting access) - Same domain configured with different acceleration or security strategies **Format Requirements**: - Allows combination of numbers, English letters, `.`, `-`, and `_` - Length limit: within 200 characters - Examples: `site-prod`, `site-test`, `site_backup` **Access Mode Restrictions**: - ✅ **CNAME Access**: Supports creating multiple sites with same name - ✅ **DNSPod Hosting Access**: Supports creating multiple sites with same name - ❌ **NS Access**: A domain can only be accessed via NS once, does not support sites with same name - ⚠️ **Mutual Exclusion Rule**: Domains accessed via NS cannot use other access modes; domains accessed via CNAME/DNSPod hosting cannot use NS access ### Site Status Determination Logic When displaying site status to users, the effective status should be determined by evaluating the following fields from `DescribeZones` response **in order** (first match wins): | Priority | Condition | Display Status | |---|---|---| | 1 | `Status == "initializing"` | Initializing — **must be filtered out, do not display to user** | | 2 | `Status == "forbidden"` | forbidden | | 3 | `Status == "deleted"` | Deleted | | 4 | `ActiveStatus == "changing"` | Changing | | 5 | `ActiveStatus == "inPausing"` | Pausing | | 6 | `Paused == true` | Paused | | 7 | None of the above | Active | > **Important**: This logic must be applied in all scenarios where site status is displayed, including site selection (D0) and status queries (F). ## Access Mode Description EdgeOne supports four site access modes: ### Access Modes with Domain 1. **DNSPod Hosting Access** (dnspodAccess) - **Prerequisites**: Domain is hosted in DNSPod and status is normal - **Advantages**: EdgeOne can directly and automatically complete ownership verification and configuration, best experience - **Recommendation**: Strongly recommended if conditions are met - **Available Features**: Layer 7 acceleration, Layer 4 proxy, security protection, edge functions 2. **NS Access** (full) - **Requirements**: Need to switch NS records to EdgeOne-provided Name Servers at domain registrar - **Characteristics**: EdgeOne fully takes over domain DNS resolution - **Available Features**: Layer 7 acceleration, Layer 4 proxy, security protection, edge functions, DNS resolution 3. **CNAME Access** (partial) - **Requirements**: Need to manually add TXT record to verify ownership - **Characteristics**: Only need to configure CNAME record pointing to EdgeOne, NS record unchanged - **Available Features**: Layer 7 acceleration, Layer 4 proxy, security protection, edge functions ### Access Mode without Domain 4. **No Domain Access** (noDomainAccess) - **Applicable Scenarios**: Temporarily no domain, or only need Layer 4 proxy and edge functions - **Characteristics**: - Can create site without providing domain - No ownership verification needed - Can directly use Layer 4 proxy and edge functions after creation - **Available Features**: Only supports Layer 4 proxy, edge functions - **Future Extension**: After site creation, can add Layer 7 acceleration domains anytime ## End-to-End Process Overview ### Access Process with Domain ``` 1. Confirm Plan (DescribePlans / DescribeAvailablePlans / CreatePlan) ↓ 2. Create Site (CreateZone) ├─ B0: Determine if domain meets specifications │ ├─ Meets → Continue with domain access process │ └─ Doesn't meet → Prompt to use no-domain access ├─ B1: Detect DNSPod hosting status (DescribeDomain) │ ├─ Meets conditions: Prioritize recommending DNSPod hosting access │ └─ Doesn't meet: Provide CNAME access and NS access ├─ B1.5: Domain conflict pre-check (CreateZone DryRun) │ ├─ No conflict → Continue creation │ ├─ CNAME/DNSPod conflict → Require AliasZoneName │ └─ NS conflict → Terminate creation (NS access is exclusive) ├─ B2: Confirm access mode and parameters │ ├─ Select access mode (DNSPod hosting / NS / CNAME) │ ├─ Select acceleration area (mainland/global requires ICP filing) │ └─ If conflict exists, provide Alias Zone Name ├─ DNSPod hosting access: Automatically complete validation, jump directly to step 4 ├─ NS access: Switch DNS server └─ CNAME access: Add TXT record or file validation ↓ 3. Verify Ownership (VerifyOwnership) — Can be skipped, verify later ↓ 4. Add Acceleration Domain (CreateAccelerationDomain) ↓ 5. Apply and Deploy HTTPS Certificate (see cert-manager.md) ↓ Onboarding Complete ``` ### No Domain Access Process ``` 1. Confirm Plan (DescribePlans / DescribeAvailablePlans / CreatePlan) ↓ 2. Create Site (CreateZone, Type = noDomainAccess) - Keep ZoneName empty - Keep Area empty - No ownership verification needed ↓ 3. Configure Layer 4 proxy or edge functions ↓ Onboarding Complete ``` > Can check verification status anytime via DescribeIdentifications. > For certificate-related queries and operations, refer to [cert-manager.md](cert-manager.md). ## Scenario A: Confirm Plan **Trigger**: First step of the process, must confirm plan before creating site. ### A1: Query Existing Plans (DescribePlans) Call `DescribePlans` to query plans under the account. #### Filter Logic From returned plan list, filter available plans by the following conditions: 1. **Bindable**: `Bindable == "true"` 2. **Normal Status**: `Status == "normal"` 3. **Sufficient Quota**: Bound sites < Site quota limit > Only plans meeting all 3 conditions above can be used for binding. #### Has Available Plans > **No Automatic Binding**: Binding plan will consume site quota. **Must** first display plan information to user and wait for explicit selection before binding; never decide on your own. **Must display all available plans** for user selection, no omissions or truncation: - If **Only 1 plan**: Still need user confirmation before use - If **Multiple plans**: - **Display Info**: Plan ID, plan type, bound site count - **Display Method**: If plan count exceeds structured interaction tool's option limit, display in batches or provide input method to ensure user can see and select all plans - **Suggested Sorting**: Sort by bound site count from least to most, convenient for user to select plans with sufficient quota - User can also choose **not to bind existing plan**, go to A2 to purchase new plan #### No Available Plans Go to A2. ### A2: Purchase New Plan (DescribeAvailablePlans → CreatePlan) Call `DescribeAvailablePlans` to query plan types available for purchase under current account, display options to user. > **No Automatic Purchase**: Purchasing plan will incur actual charges. **Must** display plan type and pricing info to user, and wait for explicit confirmation before calling `CreatePlan`. Never skip confirmation or decide on your own. After user explicit confirmation, call `CreatePlan` to purchase plan. If user confirms not to purchase, remind: **Site needs to be bound to plan to provide normal service**. Sites not bound to plan will be in `init` status and unable to take effect. ### Next Step After plan confirmation, carry PlanId to [Scenario B: Create Site](#scenario-b-create-site). ## Scenario B: Create Site **Trigger**: User says "onboard example.com to EdgeOne", "create site", "create new site", or subsequent step after plan confirmation. > If user directly triggers this scenario (without going through Scenario A), must first guide through [Scenario A: Confirm Plan](#scenario-a-confirm-plan) before continuing. > **No Automatic Creation**: Creating site will consume plan's site quota. **Must** confirm site domain, access mode, and acceleration area with user before execution; never decide on your own. ### B0: Determine Access Mode Type **First determine if the site name provided by user meets domain specifications**: 1. **Meets domain specifications** (e.g., `example.com`, `test.com.cn`): - Enter access process with domain → Go to [B1: Detect DNSPod Hosting Status](#b1-detect-dnspod-hosting-status) 2. **Doesn't meet domain specifications or user explicitly indicates no domain**: - Prompt user: "The site name you provided doesn't meet domain specifications. EdgeOne supports no-domain access mode, which is limited to Layer 4 proxy and edge functions, and Layer 7 acceleration domains can be added later. Do you want to use no-domain access mode?" - If user confirms → Go to [B3: No Domain Access](#b3-no-domain-access) - If user declines → Prompt user to provide valid second-level domain > **Domain Specifications**: Valid second-level domain (e.g., example.com), does not accept third-level and above domains (e.g., www.example.com) as site name. ### B1: Detect DNSPod Hosting Status Before displaying access mode options to user, first try to detect if domain is hosted in DNSPod to prioritize recommending DNSPod hosting access mode. **Steps:** 1. **Call DNSPod's DescribeDomain interface**, pass in the domain to onboard 2. **Determine if DNSPod hosting access conditions are met**: - Domain exists in DNSPod - `Status` field is `ENABLE` or `LOCK` - `DnsStatus` field is empty string (normal status) 3. **Exception Handling**: - If interface call fails (e.g., no permission, service unavailable), handle silently, don't display DNSPod hosting access option - If domain doesn't exist or status doesn't meet conditions, don't display DNSPod hosting access option > **Note**: The `DescribeDomain` interface only returns errors for no permission or domain not found, won't return service authorization related error codes. ### B1.5: Domain Conflict Pre-check Before formally creating site, perform pre-check to determine if domain has been accessed to avoid creation failure due to domain conflict. **Steps:** 1. **Call CreateZone interface for pre-check** - Pass parameter `DryRun: true` - Pass domain to onboard `ZoneName` - Pass user-selected access mode `Type` 2. **Determine pre-check result**: **a) Pre-check succeeds** (no error returned) - Indicates domain hasn't been accessed, can directly create - Go to [B2: Confirm Access Mode and Parameters](#b2-confirm-access-mode-and-parameters) **b) Returns `ResourceInUse.Zone` error** - Indicates domain has been accessed via CNAME or DNSPod hosting - Prompt user: "This domain has been accessed, need to set Alias Zone Name to distinguish different sites" - Guide user to provide `AliasZoneName` (Alias Zone Name) - Go to [B2: Confirm Access Mode and Parameters](#b2-confirm-access-mode-and-parameters) **c) Returns `ResourceInUse.Others` or `ResourceInUse.OthersNS` error** - Indicates domain has been accessed via **NS access** - Prompt user: "This domain has been accessed via NS access. NS access sites can only be accessed once and cannot use other access modes. If you want to use other access modes, please delete the existing NS access site first." - **Terminate creation process** > **Important Notes**: > - NS access has exclusivity; a domain can only be accessed via NS once > - Domains accessed via NS cannot use CNAME or DNSPod hosting access > - Domains accessed via CNAME or DNSPod hosting cannot use NS access (but can continue using CNAME or DNSPod hosting to create sites with same name) ### B2: Confirm Access Mode and Parameters **Call** `CreateZone`. User needs to provide: - **Site Domain**: Root domain to onboard - **Access Mode**: Display available options based on B1 detection results - If DNSPod hosting conditions are met: **Prioritize recommending** DNSPod hosting access (dnspod), also provide CNAME access (partial) and NS access (full) options - If conditions not met: Only provide CNAME access (partial) and NS access (full) options - **Acceleration Area** (Area): Optional values are mainland (Mainland China), overseas (Global excluding Mainland China), global (Global) - **mainland (Mainland China)**: ⚠️ **Requires domain to have completed ICP filing with MIIT** - **global (Global)**: ⚠️ **Requires domain to have completed ICP filing with MIIT** - **overseas (Global excluding Mainland China)**: No filing requirement - **Alias Zone Name** (AliasZoneName): **Only needed when B1.5 pre-check returns domain conflict** - Provided by user to distinguish sites with same name - Format requirements: combination of numbers, English letters, `.`, `-`, `_`, within 200 characters > **Important Notes**: > - When selecting `mainland` or `global` area, must remind user to confirm domain has completed ICP filing, otherwise site will not be able to onboard and use normally. > - If B1.5 pre-check finds domain conflict, must require user to provide `AliasZoneName` parameter. Suggest passing PlanId directly when creating. > When not passing PlanId, site is in `init` status, need to bind later via BindZoneToPlan. > > **No Automatic Binding**: Whether passing PlanId via `CreateZone` or later calling `BindZoneToPlan`, **must** obtain user's explicit confirmation beforehand; never decide on your own which plan to bind. #### Exception Handling: Service Authorization Missing **Only when user selects DNSPod hosting access mode**, calling `CreateZone` may return error code `OperationDenied.DNSPodUnauthorizedRoleOperation`, indicating service authorization is missing. **Handling Steps**: 1. **Automatically create service authorization**: Call CAM's `CreateServiceLinkedRole` interface - `QCSServiceName`: `["DnspodaccesEO.TEO.cloud.tencent.com"]` - `Description`: `"This role is a service-linked role for Tencent EdgeOne Platform (TEO). This role will query your domain status and related DNS records in DNSPod within the permission scope of associated policies, and help you quickly complete DNS modification to switch acceleration service to EO in one-click DNS modification scenarios"` 2. **Retry site creation**: - If service authorization creation succeeds, retry calling `CreateZone` to create site - If service authorization creation fails, enable fallback mode: prompt user to use NS access or CNAME access ### Next Step for DNSPod Hosting Access > In DNSPod hosting access mode, EdgeOne will automatically complete ownership verification. After site creation succeeds: - Site will automatically complete ownership verification - Can directly go to [Scenario D: Add Acceleration Domain](#scenario-d-add-acceleration-domain) ### Next Step for NS Access Inform user that they need to modify DNS server to NameServers returned in response at domain registrar, then go to [Scenario C: Verify Ownership](#scenario-c-verify-ownership). ### Next Step for CNAME Access Inform user of two validation methods (choose one), get validation info from response: 1. **DNS Validation**: Add TXT record in DNS 2. **File Validation**: Place validation file in origin root directory After user confirms configuration complete, go to [Scenario C: Verify Ownership](#scenario-c-verify-ownership). ### B3: No Domain Access **Applicable Scenarios**: User temporarily has no domain or only needs Layer 4 proxy and edge functions. **Call** `CreateZone`, parameters as follows: - `Type`: `noDomainAccess` - `ZoneName`: **Keep as empty string** - `Area`: **Keep as empty string** - `PlanId`: Pass confirmed plan ID > **Important Note**: In no-domain access mode, ZoneName and Area parameters must be kept empty, otherwise interface call will fail. **After creation succeeds**: - Site needs no ownership verification - Can directly use Layer 4 proxy and edge functions - Inform user: "Site created successfully, you can now configure Layer 4 proxy or edge functions. If you need Layer 7 acceleration features, you can add acceleration domains anytime." **Follow-up Operations**: - Configure Layer 4 proxy: Refer to Layer 4 proxy related documentation - Configure edge functions: Refer to edge functions related documentation ## Scenario C: Verify Ownership **Trigger**: User says "verify site", "check DNS switch", "ownership verification", or subsequent step after site creation. > User can choose to skip ownership verification and directly go to [Scenario D: Add Acceleration Domain](#scenario-d-add-acceleration-domain), verify later. ### C1: Query Verification Status (DescribeIdentifications) Before triggering verification, first call `DescribeIdentifications` to query current verification status. **Decision**: - If `Status` is `finished`, no need to verify again, go directly to next step - If `Status` is `pending`, inform user to configure DNS TXT record or file validation based on validation info in response ### C2: Trigger Verification (VerifyOwnership) After user confirms DNS / file configuration complete, call `VerifyOwnership`. **NS Access Scenario**: Verify if DNS server switch succeeded. DNS switch usually takes 24-48 hours to take effect globally; if verification fails, suggest user retry later. **CNAME Access Scenario**: Verify if TXT record or file is configured correctly. If site passes ownership verification, adding domains later won't need verification again. ## Scenario D: Add Acceleration Domain **Trigger**: User says "add domain", "configure acceleration domain", "onboard subdomain", or subsequent step after ownership verification completion (or skip). > **No-Domain Access Sites**: Sites created via no-domain access mode can also add Layer 7 acceleration domains anytime; after adding, can use complete Layer 7 acceleration features. ### D0: Determine Target Site > If entering this scenario from a continuous flow of Scenario B/C, ZoneId is already known; you can skip this step and go directly to D1. When user directly triggers "add domain", you need to first determine which site to add the domain to. **Steps:** 1. **Extract root domain**: Extract the root domain (e.g., `example.com`) from the acceleration domain provided by user (e.g., `www.example.com`). 2. **Query matching sites**: Call `DescribeZones` with `zone-name` filter by root domain: ``` --Filters '[{"Name":"zone-name","Values":["example.com"]}]' ``` 3. **Filter and handle based on query results**: First, filter out sites with `Status == "initializing"` — these sites are still initializing and must not be displayed. Then handle the remaining sites: - **No matching site** (or all filtered out): Prompt user that the root domain has not been onboarded to EdgeOne, guide to [Scenario A: Confirm Plan](#scenario-a-confirm-plan) to begin full onboarding process. - **Only 1 site**: Display site info (ZoneId, alias, access mode, acceleration area, status) to user, proceed to D1 after confirmation. - **Multiple sites** (same root domain may have multiple sites): **Must** display all matching sites for user selection; never automatically select the first one or any arbitrary one. Display info should include: - **Site Alias** (AliasZoneName) — the most intuitive distinguishing identifier - **ZoneId** - **Access Mode** (Type: dnsPodAccess / partial / full) - **Acceleration Area** (Area: mainland / overseas / global) - **Status**: Determined using the [Site Status Determination Logic](#site-status-determination-logic) - Suggest prioritizing sites with `Active` status > **No Automatic Selection**: When multiple matching sites exist, **must** wait for user's explicit selection before continuing; never decide on your own. ### D1: Collect Parameters Need to confirm following information with user before calling: 1. **Acceleration Domain** (DomainName): Subdomain to onboard, e.g., `www.example.com` 2. **IPv6 Access** (IPv6Status): Whether to enable IPv6 access, values: - `follow`: Follow site IPv6 configuration (default) - `on`: Enable - `off`: Disable 3. **Origin Configuration** (OriginInfo): See [OriginInfo Data Structure](#origininfo-data-structure) below 4. **Origin Protocol** (OriginProtocol, optional): FOLLOW (default) / HTTP / HTTPS 5. **Origin Port** (optional): HTTP origin port (default 80) / HTTPS origin port (default 443) #### OriginInfo Data Structure OriginInfo is a required parameter for `CreateAccelerationDomain`, defining origin information. ##### Required Fields | Field | Type | Description | |---|---|---| | **OriginType** | string | Origin type, see values below | | **Origin** | string | Origin address, fill in different values based on OriginType | ##### OriginType Values and Origin Mapping | OriginType | Description | Origin Value | |---|---|---| | `IP_DOMAIN` | IPv4, IPv6, or domain type origin | IP address or domain, e.g., `1.1.1.1`, `origin.example.com` | | `COS` | Tencent Cloud COS object storage origin | COS bucket access domain | | `AWS_S3` | AWS S3 object storage origin | S3 bucket access domain | | `ORIGIN_GROUP` | Origin group type origin | Origin group ID; if referencing another site's origin group, format: `{OriginGroupID}@{ZoneID}` | | `VOD` | Cloud VOD | Cloud VOD application ID | | `LB` | Load balancer (whitelist only) | Load balancer instance ID; if referencing another site's LB, format: `{LBID}@{ZoneID}` | | `SPACE` | Origin offload (whitelist only) | Origin offload space ID | ##### Optional Fields | Field | Type | Applicable Scenario | Description | |---|---|---|---| | **HostHeader** | string | Only when `OriginType = IP_DOMAIN` | Custom origin HOST header. **Do not pass this field** for other origin types, otherwise it will cause errors | | **PrivateAccess** | string | Only when `OriginType = COS` or `AWS_S3` | Whether to use private authentication: `on` / `off` (default off) | | **PrivateParameters** | list | Only when `PrivateAccess = on` | Private authentication parameter list | | **BackupOrigin** | string | Only when `OriginType = ORIGIN_GROUP` | Backup origin group ID (legacy feature, not recommended) | | **VodOriginScope** | string | Only when `OriginType = VOD` | Origin scope: `all` (default, all files in app) / `bucket` (specified bucket) | | **VodBucketId** | string | Only when `OriginType = VOD` and `VodOriginScope = bucket` | VOD bucket ID | ##### Most Common Scenario Examples **IP/Domain origin** (most common): ```json { "OriginType": "IP_DOMAIN", "Origin": "1.1.1.1" } ``` **COS origin (private access)**: ```json { "OriginType": "COS", "Origin": "bucket-xxx.cos.ap-guangzhou.myqcloud.com", "PrivateAccess": "on", "PrivateParameters": [{"Name": "SecretId", "Value": "xxx"}, {"Name": "SecretKey", "Value": "xxx"}] } ``` **Origin group**: ```json { "OriginType": "ORIGIN_GROUP", "Origin": "og-testorigin" } ``` ### D2: Call CreateAccelerationDomain > **No Automatic Addition**: Adding acceleration domain will change online DNS configuration. **Must** complete parameter collection in D1 and obtain user's explicit confirmation before execution; never decide on your own. Call `CreateAccelerationDomain` after user confirmation. **Next Step**: Inform user that they need to add CNAME record in DNS, pointing domain to EdgeOne-assigned CNAME address (can query `Cname` field via `DescribeAccelerationDomains`). ## Scenario E: Apply and Deploy HTTPS Certificate **Trigger**: After domain addition complete, user says "configure HTTPS", "apply for certificate", or as final step of onboarding process. > Complete certificate management (CNAME manual validation, deploy custom certificate, batch inspection, etc.) refer to [cert-manager.md](cert-manager.md). ### E1: NS Access / DNSPod Hosting Access (Automatic Validation, One-Step Complete) > **Applicable Scenarios**: In NS access mode or DNSPod hosting access mode, EdgeOne can directly control DNS records, so can automatically complete certificate application and deployment. > **No Automatic Deployment**: Deploying certificate will directly affect domain's HTTPS service. **Must** inform user which domains will deploy which certificates, and wait for explicit confirmation before calling `ModifyHostsCertificate`. ### E2: CNAME Access (Manual Validation) CNAME access needs to first apply for certificate, complete domain validation, then deploy; process is longer. Please refer to [cert-manager.md Scenario B2](cert-manager.md#b2-cname-access-manual-validation) for complete steps. ## Scenario F: View Onboarding Status **Trigger**: User says "check site status", "is domain onboarded". Call `DescribeZones` to query target site status. > **Important**: When displaying site status, must use the [Site Status Determination Logic](#site-status-determination-logic) to determine and display the effective status. Sites with `Status == "initializing"` must be filtered out and not displayed to users. > Refer to [../api/zone-discovery.md](../api/zone-discovery.md) for more query methods. FILE:references/api/README.md # EdgeOne API Reference EdgeOne (Edge Security Acceleration Platform) is managed through Tencent Cloud API. Currently uses **tccli** (Tencent Cloud CLI) as the calling tool, with service name **teo**. ## Files in This Directory | File | Applicable Scenarios | |---|---| | `install.md` | First-time setup: install tccli (pipx / Homebrew), prepare Python environment | | `auth.md` | tccli is installed but missing credentials — browser OAuth login, logout, or multi-account management | | `api-discovery.md` | Find API endpoints — search best practices, API lists, and documentation via cloudcache | | `zone-discovery.md` | Get zone / domain info: ZoneId lookup, reverse domain lookup, pagination handling | | `dnspod-integration.md` | DNSPod hosting access: detect domain hosting status, service authorization, access process | ## Overview **tccli** is Tencent Cloud's official CLI tool, supporting all cloud API calls. **Key elements:** - **Calling format** — `tccli teo [--param value ...]` - **Auto credentials** — Browser OAuth authorization is recommended, see `auth.md` - **API discovery** — Search best practices, API lists, and documentation online via cloudcache **Calling conventions:** - **Check documentation before calling**: Except for verifying tool availability, you **must** consult the API documentation via `api-discovery.md` before calling any API to confirm the action name, required parameters, and data structures. **Never guess parameters from memory.** - If a field's type is a struct, you **must** continue looking up the full field definitions of that struct, recursively until all nested structs have been identified — do not skip or guess. | Item | Description | |---|---| | Invocation Form | `tccli teo [--param value ...]` | | Region | No `--region` by default; add `--region ` if user explicitly specifies region | | Parameter Format | Non-simple types must be standard JSON | | Serial Invocation | tccli has config file competition issues with parallel calls, please call one by one | | Error Capture | Every tccli command **must** end with `2>&1; echo "EXIT_CODE:$?"`, otherwise stderr will be swallowed and you won't see specific error messages | ## Quick Start **Before first API call in each session**, execute tool check first: ```sh tccli cvm DescribeRegions 2>&1; echo "EXIT_CODE:$?" ``` Determine next step based on result: | Result | Meaning | Next Step | |---|---|---| | Normal JSON response | Tool is installed, credentials are valid | Proceed with API operations | | `command not found` / `not found` | tccli is not installed | Read `install.md` to install | | `secretId is invalid` or auth error | tccli is installed but missing credentials | Read `auth.md` to configure credentials | ## Fallback Retrieval Sources When files in this directory don't cover content, or need to confirm latest values / limits, retrieve via the following sources. When reference files conflict with official documentation, **official documentation takes precedence**. | Source | Retrieval Method | Used For | |---|---|---| | EdgeOne API docs | [edgeone.ai/document/50454](https://edgeone.ai/document/50454) | API parameters, request examples, data structures | | teo API discovery | cloudcache commands in `api-discovery.md` | Dynamically find APIs, best practices | | Tencent Cloud CLI docs | [github.com/TencentCloud/tencentcloud-cli](https://github.com/TencentCloud/tencentcloud-cli) | tccli installation, configuration, usage | FILE:references/api/api-discovery.md # EdgeOne API Discovery The tccli service name for EdgeOne is **teo**. Typically, reference files already specify the API name to call — just look up the API documentation directly; use fallback discovery only when references do not cover the scenario. --- ## Main Flow: Known API Name ### 1. Read the API Documentation Get parameter descriptions and request examples for a specific API: ```sh curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/action/CreatePurgeTask.md ``` ### 2. Read Data Structures Complex data structures referenced in the API documentation can be further examined: ```sh curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/model/Task.md ``` --- ## Fallback: Not Sure Which API to Call When references do not specify an API, or you need to explore uncovered scenarios, search in the following order: ### 1. Search the API List Search for keywords in the API list (the Action name is the second argument after `tccli teo`): ```sh curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/actions.md \ | grep -i "purge\|cache" ``` ### 2. Search Best Practices Check if there are best practices matching the current scenario (with complete call examples): ```sh curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/practices.md \ | grep -i "purge\|refresh" ``` ### 3. Read Best Practice Details ```sh curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/practice/practice-53.md ``` --- FILE:references/api/auth.md # Configure TCCLI Credentials ## Login Method First, run the following command to verify the current login status: ```sh tccli cvm DescribeRegions ``` - If a normal result is returned, you are already logged in — no need to log in again. - If it shows `secretId is invalid` or other authentication errors, you are not logged in and need to continue with the login command below. Browser-based authorization login is recommended — no need to manually enter SecretId/SecretKey, credentials are automatically saved locally: ```sh tccli auth login ``` After execution, TCCLI will start a temporary port on your machine and print an OAuth authorization link (it usually also opens automatically in the default browser). Once the user completes login and authorization in the browser, TCCLI receives the callback, writes the credentials, and exits. - If the browser does not open automatically, copy the link printed in the terminal and open it manually in a browser. - Upon success, it will display: "Login successful, credentials have been written to: ..." --- ## Agent Operating Guidelines **Determining whether login is needed:** 1. First run `tccli cvm DescribeRegions`. 2. If a **reasonable success result** is returned, consider the user logged in and proceed with subsequent operations. 3. If an error is returned or the command cannot execute, you must first run `tccli auth login`. 4. Never ask the user for `SecretId` / `SecretKey`, and do not execute commands that might expose credential contents (especially `tccli configure list`). > ⚠️ The Agent must not assume TCCLI is usable based solely on the user's verbal statement or potentially stale credential files on the machine. **When running `tccli auth login`:** - This command will **block** until the user completes browser login (or it times out). - The Agent should clearly inform the user: "Please open the authorization link shown in the terminal/tool output and complete login in the browser; the command will end automatically once done." --- ## Multi-Account & Logout | Operation | Command | |------|------| | Login default account | `tccli auth login` | | Login specific account | `tccli auth login --profile user1` | | Logout default account | `tccli auth logout` | | Logout specific account | `tccli auth logout --profile user1` | Credential file notes: - Default account credentials are saved in `default.credential` - Specific account credentials are saved in `.credential` (e.g., `user1.credential`) ## Security Reminder > Using `tccli configure` to manually enter SecretId / SecretKey is **not recommended**. Manually configured keys are stored in plaintext locally and risk being leaked. Always use the `tccli auth login` browser authorization method. FILE:references/api/dnspod-integration.md # DNSPod Integration API Reference EdgeOne supports DNSPod hosting access mode, enabling one-click domain onboarding and automated configuration. This document explains how to call related APIs. ## Query Domain Hosting Status ### DescribeDomain (DNSPod) **Purpose**: Query whether domain is hosted in DNSPod and if hosting status meets EdgeOne access conditions. **Invocation Example**: ```bash tccli dnspod DescribeDomain --Domain "example.com" ``` **Key Response Fields**: ```json { "DomainInfo": { "Domain": "example.com", "DomainId": 12345678, "Status": "ENABLE", // Domain status: ENABLE(normal), PAUSE(paused), SPAM(blocked) "DnsStatus": "", // DNS status: empty string(normal), "dnserror"(abnormal) "Grade": "DP_Pro", // Plan level "DnspodNsList": [ // DNSPod's NS list "ns1.dnspod.net", "ns2.dnspod.net" ], "ActualNsList": [ // Actual NS used by domain "ns1.dnspod.net", "ns2.dnspod.net" ] } } ``` **EdgeOne Access Condition Determination**: Domain can use DNSPod hosting access when meeting all of the following conditions: 1. ✅ Domain exists (interface call succeeds) 2. ✅ `Status` field is `"ENABLE"` or `"LOCK"` 3. ✅ `DnsStatus` field is empty string `""` **Common Error Handling**: | Error Code | Description | Handling Method | |--------|------|----------| | `ResourceNotFound.NoDataOfDomain` | Domain doesn't exist in DNSPod | Don't display DNSPod hosting access option | | `OperationDenied.DNSPodUnauthorizedRoleOperation` | Missing service authorization | Try to automatically create service authorization role | | `UnauthorizedOperation` | User lacks DNSPod interface permission | Don't display DNSPod hosting access option | ## Create Service-Linked Role ### CreateServiceLinkedRole (CAM) **Purpose**: Create service authorization role for EdgeOne to access DNSPod for user. **Trigger Scenario**: When calling `DescribeDomain` interface returns `OperationDenied.DNSPodUnauthorizedRoleOperation` error. **Invocation Example**: ```bash tccli cam CreateServiceLinkedRole \ --QCSServiceName '["DnspodaccesEO.TEO.cloud.tencent.com"]' \ --Description "This role is a service-linked role for Tencent EdgeOne Platform (TEO). This role will query your domain status and related DNS records in DNSPod within the permission scope of associated policies, and help you quickly complete DNS modification to switch acceleration service to EO in one-click DNS modification scenarios" ``` **Response Example**: ```json { "RoleId": "4611686018428516331", "RequestId": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } ``` **Follow-up Actions**: - ✅ If creation succeeds: Retry calling `DescribeDomain` to detect domain status - ❌ If creation fails: Enable fallback mode, don't display DNSPod hosting access option ## DNSPod Hosting Access Process ### Complete Invocation Flow ```mermaid graph TD A[Start Access] --> B[Call DescribeDomain] B --> C{Domain Exists?} C -->|No| D[Don't Display DNSPod Hosting Access] C -->|Yes| E{Status and DnsStatus Meet Conditions?} E -->|No| D E -->|Yes| F[Display DNSPod Hosting Access as Preferred] B --> G{Error Code is Authorization Error?} G -->|Yes| H[Call CreateServiceLinkedRole] H --> I{Creation Succeeds?} I -->|Yes| B I -->|No| D G -->|No| J{Other Permission Errors?} J -->|Yes| D F --> K[User Selects DNSPod Hosting Access] K --> L[Call CreateZone Type=dnspod] L --> M[Automatically Complete Ownership Verification] M --> N[Add Acceleration Domain] ``` ### Access Mode Parameters When calling `CreateZone`, optional values for `Type` parameter: - `dnspod`: DNSPod hosting access - `full`: NS access - `partial`: CNAME access **Recommendation Strategy**: 1. Prioritize detecting if DNSPod hosting access conditions are met 2. If met, display `dnspod` as **preferred recommendation** to user 3. Always provide `full` and `partial` as alternative options ## Best Practices ### 1. Silent Detection, Smart Recommendation ```python # Pseudo-code example def get_available_access_types(domain): access_types = [] # Try to detect DNSPod hosting status try: response = dnspod.DescribeDomain(Domain=domain) domain_info = response['DomainInfo'] # Determine if conditions are met if (domain_info['Status'] in ['ENABLE', 'LOCK'] and domain_info['DnsStatus'] == ''): access_types.append({ 'type': 'dnspod', 'name': 'DNSPod Hosting Access', 'recommended': True, 'description': 'No manual configuration needed, automatically completes validation' }) except DNSPodUnauthorizedRoleOperation: # Try automatic authorization try: cam.CreateServiceLinkedRole(...) # Retry detection return get_available_access_types(domain) except: pass # Authorization failed, use fallback plan except: pass # Other errors, use fallback plan # Fallback: Always provide NS and CNAME access access_types.extend([ {'type': 'full', 'name': 'NS Access'}, {'type': 'partial', 'name': 'CNAME Access'} ]) return access_types ``` ### 2. User Experience Optimization **Suggested Wording When Displaying to User**: ✅ **When DNSPod Hosting Conditions Are Met**: > Detected that your domain `example.com` is hosted in DNSPod. Recommend using **DNSPod Hosting Access** mode, which can automatically complete validation and configuration without manual DNS operations. > > You can also choose other access modes: > - NS Access: Need to modify domain's NS record > - CNAME Access: Need to add TXT record to verify ownership ❌ **When DNSPod Hosting Conditions Are Not Met**: > Please select access mode: > - NS Access: EdgeOne fully takes over DNS resolution > - CNAME Access: Only configure CNAME record, NS unchanged ### 3. Error Handling Suggestions | Scenario | User Prompt | Technical Handling | |------|----------|----------| | Domain Not in DNSPod | No prompt, directly provide NS/CNAME options | Handle silently | | Missing Service Authorization | "Configuring service authorization for you..." | Automatically call CreateServiceLinkedRole | | Authorization Creation Failed | No prompt, directly provide NS/CNAME options | Silently fall back to fallback plan | | Domain Status Abnormal | No prompt, directly provide NS/CNAME options | Handle silently | ## Reference Materials - [DNSPod API Documentation](https://cloud.tencent.com/document/product/1427) - [CAM Service-Linked Roles](https://cloud.tencent.com/document/product/598/19388) - [EdgeOne CreateZone Interface](https://cloud.tencent.com/document/product/1552/80719) FILE:references/api/install.md # API Calling Environment Setup EdgeOne APIs are called via **tccli** (Tencent Cloud CLI). ## 1. Choose an Installation Method | Method | Use Case | Prerequisites | |---|---|---| | **pipx** | All platforms, auto-isolated environment | Python 3.8+ | | **Homebrew** | macOS | No Python required | - macOS with Homebrew already installed → go directly with the Homebrew route, skip to Step 4 - Otherwise → go with the pipx route, continue to Step 2 ## 2. Ensure Python Environment (pipx Route) ```sh python3 --version ``` If the version is ≥ 3.8, skip to the next step. If the command is not found or the version is too old, install by OS: ```sh # macOS (via Homebrew) brew install python@3 # Ubuntu / Debian apt update && apt install -y python3 python3-pip # Windows (via winget) winget install Python.Python.3.12 # Or download from: https://www.python.org/downloads/ ``` After installation, run `python3 --version` to confirm version ≥ 3.8. ## 3. Install pipx (pipx Route) ```sh pipx --version ``` If already installed, skip to the next step; otherwise install by OS: ```sh # macOS brew install pipx && pipx ensurepath # Linux pip install --user pipx && pipx ensurepath # Windows pip install --user pipx && pipx ensurepath ``` ## 4. Install tccli ### pipx Route ```sh pipx install tccli # If upgrading from a version below 3.0.252.3, uninstall first then reinstall: # pipx uninstall tccli && pipx install tccli ``` ### Homebrew Route (macOS Only) ```sh brew tap tencentcloud/tccli brew install tccli # Update: brew upgrade tccli ``` ### Verify ```sh tccli --version ``` ## Next Step After installation is complete, read `auth.md` to configure credentials. FILE:references/api/zone-discovery.md # Zone & Domain Discovery Nearly all EdgeOne API operations require a **ZoneId** (zone ID, in the format `zone-xxx123abc456`). Below is the standard process for discovering ZoneIds and reverse-looking up domains. ## APIs Involved | Action | Description | API Docs | |---|---|---| | DescribeZones | Query the list of zones | `curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/action/DescribeZones.md` | | DescribeAccelerationDomains | Query the list of acceleration domains | `curl -s https://cloudcache.tencentcs.com/capi/refs/service/teo/action/DescribeAccelerationDomains.md` | Check the API docs above before calling, to get the exact usage of Filters, pagination, and other parameters. ## 1. List All Zones Call **DescribeZones** — the `Zones` array in the response contains each zone's `ZoneId`, `ZoneName` (zone domain), `Status`, and other info. > **Important**: > > 1. **Pagination Mechanism**: DescribeZones returns a maximum of 20 records per request by default. **Must use pagination mechanism** to retrieve all zones: > > 2. **Status Filtering**: After retrieving the zone list, **must filter out** zones with `Status` as `initializing`: > - These zones are initializing and have not completed creation > - Should not be displayed to users or used for subsequent operations > - Only display and use available zones with `Status` as `active` > > **Pagination Parameters**: > - `Limit`: Maximum number of records returned per request, recommend setting to `100` (maximum value) > - `Offset`: Offset, starting from `0`, increment by `Limit` value each iteration > > **Pagination Logic**: > ``` > 1. Initial call: Offset=0, Limit=100 > 2. Check TotalCount (total number of zones) in response > 3. If TotalCount > number of zones retrieved: > - Offset += 100 > - Continue calling until all zones are retrieved > 4. Merge all paginated results > ``` > > **Example (Pseudo Code)**: > ```python > all_zones = [] > offset = 0 > limit = 100 > > # Paginate to retrieve all zones > while True: > response = DescribeZones(Offset=offset, Limit=limit) > all_zones.extend(response.Zones) > > if offset + limit >= response.TotalCount: > break > offset += limit > > # Filter out zones that are initializing > available_zones = [zone for zone in all_zones if zone.Status != 'initializing'] > ``` ## 2. Query by Zone Name When the user already knows the zone domain, call **DescribeZones** with `Filters` (`zone-name`) for an exact match. > **Note**: The query results also need to check the `Status` field and filter out zones with `initializing` status. ## 3. Reverse-Lookup ZoneId from a Subdomain When the user only provides a subdomain (e.g., `www.example.com`) and doesn't know the ZoneId: 1. First call **DescribeZones** to list all zones, and find the ZoneId corresponding to the root domain matching the subdomain > **Must use pagination**: Refer to the pagination mechanism in "1. List All Zones" to ensure traversing **all** zones for matching 2. Then call **DescribeAccelerationDomains** with `Filters` (`domain-name`) to confirm the domain exists under the zone ## 4. List All Domains Under a Zone Call **DescribeAccelerationDomains** with the `ZoneId`. Be sure to use pagination parameters to handle multi-page results. ## 5. ZoneId Caching Recommendation Within the same session, previously discovered ZoneIds should be remembered and reused to avoid repeated calls to `DescribeZones`. FILE:references/observability/README.md # EdgeOne Observability Reference Operational guides for traffic daily report generation, origin health inspection, offline log download, and log analysis. ## Quick Decision Tree ``` What does the user want to do? │ ├─ "Generate yesterday's traffic daily report" │ "Show me the bandwidth peak over the last 24 hours" │ └─ → `eo-traffic-daily-report.md` 🟢 Low Risk · Auto-collect L7/L4 data and generate a Markdown daily report │ ├─ "Check the origin status for example.com" │ "Is the origin healthy?" "Is it a CDN issue or an origin issue?" │ └─ → `eo-origin-health-check.md` 🟢 Low Risk · Origin status code distribution + health ratio + quick root cause analysis │ ├─ "Download the logs for example.com from yesterday afternoon" │ "Download the last 6 hours of L4 logs" │ └─ → `eo-log-downloader.md` 🟢 Low Risk · Natural language driven offline log download link retrieval │ ├─ "Analyze the logs — too many 502 errors" │ "Which URIs have the most abnormal requests?" │ "Show me per-URL download traffic breakdown" │ └─ → `eo-log-analyzer.md` 🟢 Low Risk · Log download + local parsing + pattern recognition + fault inference + traffic aggregation │ └─ Not sure which API to call └─ → `../api/api-discovery.md` ``` ## Prerequisites All operations require API calls via tccli. Before first use, complete the following: 1. **Tool Setup** — Read `../api/README.md` to install tccli and configure credentials 2. **Get ZoneId** — Read `../api/zone-discovery.md` to obtain the zone ID ## Files in This Directory | File | Risk Level | Core Trigger Scenario | |---|---|---| | `eo-traffic-daily-report.md` | 🟢 Low Risk | Query L7/L4 traffic trends daily and generate a Markdown report with bandwidth peak, request volume, and Top domains/regions | | `eo-origin-health-check.md` | 🟢 Low Risk | Query origin status code distribution and origin health ratio for quick origin fault root cause analysis | | `eo-log-downloader.md` | 🟢 Low Risk | Describe time range and domain in natural language to automatically retrieve offline log download links | | `eo-log-analyzer.md` | 🟢 Low Risk | Automatically download and parse logs locally, extract anomaly details, provide pattern recognition conclusions with fault inference, or aggregate traffic by domain/URL | ## Reference Links - [EdgeOne Product Documentation](https://edgeone.ai/document/56978) - [EdgeOne API Documentation](https://edgeone.ai/document/50454) - `../api/README.md` FILE:references/observability/eo-log-analyzer.md # eo-log-analyzer Users describe a fault time period and domain to automatically download logs, parse them locally, extract anomaly details, and provide pattern recognition conclusions with fault inference recommendations. Also supports traffic aggregation analysis (e.g., per-URL download volume breakdown). This is an upgrade from `eo-log-downloader.md`, which only provides download links — this scenario further completes log parsing and analysis. ## APIs & Prerequisites Same as `eo-log-downloader.md` — this scenario uses the same APIs (`DownloadL7Logs`, `DownloadL4Logs`, `DescribeAccelerationDomains`) and the same prerequisites (`tccli` authentication + ZoneId discovery). Refer to that document for full details. ## Special Design Notes - **Read-only operations**: All API calls are read-only queries; log downloading and parsing are performed locally - **Local file writes only**: Log parsing is completed on the client side locally; raw logs are not uploaded or modified - **Aggregated summaries for high-traffic domains**: For domains with extremely high request volumes, use aggregated summary analysis (grouped statistics by URI/status code/IP) rather than line-by-line output of full logs, to avoid information overload - **Cross-scenario integration**: Analysis conclusions can guide the user to use `eo-origin-health-check.md` for origin troubleshooting, or `../security/ip-threat-blacklist.md` to block anomalous IPs ## Scenario A: Fault Period Log Analysis **Trigger**: User says "analyze the logs for example.com from 3 PM to 4 PM today", "too many 502 errors, help me figure out what's going on", "analyze the logs and find the anomalies". ### Workflow **Step 1**: Confirm analysis parameters - Confirm the target domain (must be specified by the user or obtained from context) - Parse the time range (natural language to ISO 8601) - Confirm the anomaly type of interest (default: 4xx + 5xx; the user may also specify a particular status code such as 502) **Step 2**: Download log files Confirm the domain, retrieve download links, and download locally: - If the user specified a subdomain (e.g., `www.example.com`), use it directly in the `Domains` parameter - If the user did not specify a domain, or provided a **root domain** (matching the `ZoneName` from `DescribeZones`), follow `eo-log-downloader.md` Scenario A Step 2 to call `DescribeAccelerationDomains` and discover subdomains first, then either let the user choose or omit `Domains` to download all Call `DownloadL7Logs` with `StartTime`, `EndTime`, `ZoneIds`, and optionally `Domains`. Then download and decompress: - Use `curl` or `wget` to download log files to a local temporary directory - Log files are typically in `.gz` compressed format; use `gunzip` to decompress - ⚠️ **Log format is JSON Lines** (one JSON object per line, newline-separated). Each line is a self-contained JSON object. Do NOT parse as tab-separated or CSV. > If there are many or large log files, prioritize downloading files that cover the user's time period of interest to avoid unnecessary bulk downloads. > **If results are empty**, follow the troubleshooting steps in `eo-log-downloader.md` Scenario A — Troubleshooting Empty Results (domain mismatch, time too recent, no traffic, wrong zone). #### L7 Offline Log Field Reference The following fields are available in offline logs (subset of all L7 fields). For the full field list, see [L7 Access Logs](https://edgeone.ai/document/61300). | Field | Type | Description | Common Use | |---|---|---|---| | `RequestTime` | ISO8601 | Time the request was received (UTC+0) | Time-window aggregation | | `RequestHost` | String | Requested hostname (subdomain) | Group by domain | | `RequestUrl` | String | URL path (without query string) | Group by resource/URI | | `RequestUrlQueryString` | String | Query string portion of the URL | Full URL reconstruction | | `RequestMethod` | String | HTTP method (GET/POST/...) | Filter by method | | `RequestBytes` | Integer | Total bytes sent from client to edge (headers + body + SSL) | Inbound traffic | | `EdgeResponseStatusCode` | Integer | Status code returned to client | Error filtering (4xx/5xx) | | `EdgeResponseBytes` | Integer | Total bytes sent from edge to client (headers + body + SSL) | **Outbound traffic / download volume** | | `EdgeResponseBodyBytes` | Integer | Response body bytes only (no headers) | Content-only traffic | | `EdgeCacheStatus` | String | Cache hit status: `hit` / `miss` / `dynamic` / `other` | Cache analysis | | `EdgeInternalTime` | Integer | Time to first byte (ms) | Latency analysis | | `EdgeResponseTime` | Integer | Time to last byte (ms) | Full response latency | | `ClientIP` | String | Client IP address | IP concentration analysis | | `ClientRegion` | String | Client country/region (ISO 3166-1 alpha-2) | Geographic analysis | | `EdgeServerIP` | String | Edge node IP | Node-level analysis | | `RequestUA` | String | User-Agent | Bot/crawler identification | | `RequestReferer` | String | Referer header | Traffic source analysis | > **Parsing tip**: Use `jq` for JSON Lines processing (install via `brew install jq` on macOS or `apt install jq` on Linux). Example: > ```sh > # Count requests grouped by status code > cat logfile.log | jq -r '.EdgeResponseStatusCode' | sort | uniq -c | sort -rn > # Sum download traffic by URL > cat logfile.log | jq -r '[.RequestUrl, .EdgeResponseBytes] | @tsv' | awk -F'\t' '{sum[$1]+=$2} END {for(u in sum) printf "%s\t%.2f MB\n", u, sum[u]/1048576}' | sort -t$'\t' -k2 -rn > ``` > > **If `jq` is not available**, use Python as a fallback: > ```sh > python3 -c " > import json, sys > from collections import defaultdict > agg = defaultdict(lambda: [0, 0]) > for line in sys.stdin: > r = json.loads(line) > agg[r.get('RequestUrl','')][0] += 1 > agg[r.get('RequestUrl','')][1] += r.get('EdgeResponseBytes', 0) > for url, (cnt, b) in sorted(agg.items(), key=lambda x: -x[1][1]): > print(f'{url}\t{cnt}\t{b/1048576:.2f} MB') > " < logfile.log > ``` **Step 3**: Parse logs and extract anomalies Perform structured parsing on the decompressed logs: - Filter anomalous requests by status code (4xx, 5xx) - Aggregate anomalous request count and ratio by URI - Aggregate by client IP to identify request concentration - Aggregate by time window (e.g., 5-minute granularity) to identify anomaly peak periods **Step 4**: Pattern recognition Perform pattern analysis on the aggregated data: | Pattern | Characteristics | Possible Cause | |---|---|---| | Single URI concentrated 502 | One URI has a much higher 502 ratio than others | The backend service for that URI is malfunctioning | | IP-concentrated anomalous requests | A few IPs generate a large number of anomalous requests | Possible crawler, attack, or malfunctioning client | | Global 5xx spike | All URIs show concentrated 5xx in the same time period | Overall origin server overload or failure | | Intermittent 504 | 504 errors appear repeatedly in specific time windows | Origin response timeout, possible performance bottleneck | **Step 5**: Output analysis report Summarize the anomaly details table, pattern recognition conclusions, and fault inference recommendations. **Output recommendation**: Present the response as "overview summary + anomalous URI Top N table + pattern recognition conclusions + recommendations". ## Scenario B: Identify Origin Failure Concentration Periods **Trigger**: User says "show me when origin failures were concentrated recently", "which time period had the most 5xx errors", "help me find the fault peak periods". ### Workflow **Step 1**: Confirm query parameters - Confirm the target domain - Default query range is the last 6 hours; the user may also specify a different time range **Step 2**: Download and parse logs Same as Scenario A Steps 2 and 3, but focus on time-window aggregation: - Use 5-minute or 10-minute granularity to count 5xx requests per time window - Calculate the 5xx ratio for each window **Step 3**: Identify peak periods - Mark the Top 3 time periods with the highest 5xx count - Calculate the deviation multiplier of peak periods from the average **Step 4**: Output time distribution Organize the time distribution into a table, highlight peak periods, and provide further analysis recommendations. **Output recommendation**: Present the response as "time distribution table + peak period annotations + next-step recommendations". ## Scenario C: Traffic / Download Volume Aggregation by Domain + URL **Trigger**: User says "which resources use the most bandwidth", "show me download traffic by URL", "I want to see per-resource traffic breakdown", "which URLs are consuming the most traffic". ### Workflow **Step 1**: Confirm analysis parameters - Confirm the target domain (or all domains under the zone) - Parse the time range (natural language to ISO 8601) - Confirm the aggregation dimension: by URL only, by domain + URL, or by domain only **Step 2**: Download log files Same as Scenario A Step 2. Download and decompress the log files for the target time range. **Step 3**: Aggregate traffic data Parse each JSON line and aggregate by the requested dimension: - **Primary metric**: `EdgeResponseBytes` (total bytes delivered to client, including headers) — this represents the **download traffic** from the user's perspective - **Secondary metric**: `EdgeResponseBodyBytes` (response body only) — useful when isolating content size from protocol overhead - Group by `RequestHost` + `RequestUrl` (or `RequestHost` alone, or `RequestUrl` alone, depending on user intent) - Also count the number of requests per group for context Example aggregation using `jq` + `awk` (if `jq` is available): ```sh # Traffic by domain + URL, sorted descending by MB value cat *.log | jq -r '[.RequestHost, .RequestUrl, (.EdgeResponseBytes | tostring)] | @tsv' \ | awk -F'\t' '{key=$1"\t"$2; sum[key]+=$3; cnt[key]++} END {for(k in sum) printf "%s\t%d\t%.2f\n", k, cnt[k], sum[k]/1048576}' \ | sort -t$'\t' -k4 -rn | head -50 ``` If `jq` is not available, use Python: ```sh python3 -c " import json, sys, os from collections import defaultdict agg = defaultdict(lambda: [0, 0, 0]) # [requests, bytes, body_bytes] for fname in sorted(f for f in os.listdir('.') if f.endswith('.log') or not '.' in f): with open(fname) as fh: for line in fh: line = line.strip() if not line: continue r = json.loads(line) key = (r.get('RequestHost',''), r.get('RequestUrl','')) agg[key][0] += 1 agg[key][1] += r.get('EdgeResponseBytes', 0) agg[key][2] += r.get('EdgeResponseBodyBytes', 0) for (host, url), (cnt, b, bb) in sorted(agg.items(), key=lambda x: -x[1][1]): print(f'{host}\t{url}\t{cnt}\t{b/1048576:.2f} MB') " ``` **Step 4**: Enrich with cache and status insights (optional) For the Top N resources by traffic, additionally aggregate: - `EdgeCacheStatus` distribution (`hit` / `miss` / `dynamic`) — helps identify cacheable resources that are not being cached - `EdgeResponseStatusCode` distribution — detect if high-traffic resources also have high error rates **Step 5**: Output traffic report Summarize the aggregation results with the Top N table and optional insights. **Output recommendation**: Present as "overview summary + Top N traffic table + cache/status insights + optimization recommendations". ## Output Format ### Scenario A: Log Analysis Report ```markdown ## Log Analysis Report — **Zone**: (ZoneId: ) **Analysis Time Period**: – **Total Requests**: | **Anomalous Requests**: (%) ### Anomalous URI Top 10 | URI | Anomaly Count | Ratio of Total Anomalies | Primary Error Code | Source IP Concentration | |---|---|---|---|---| | ... | ... | ...% | 502 | Dispersed / Concentrated (N IPs) | ### Pattern Recognition - - ### Recommendations 1. (consider using eo-origin-health-check for origin troubleshooting) 2. (consider using ip-threat-blacklist to block anomalous IPs) ``` ### Scenario B: Origin Failure Time Distribution ```markdown ## Origin Failure Time Distribution — (Last Hours) **Analysis Time Range**: – | Time Period | 5xx Count | Ratio | Remarks | |---|---|---|---| | HH:MM–HH:MM | ... | ...% | Peak ⚠️ | | ... | ... | ...% | | ### Conclusion - Failures are concentrated in . Recommend focusing analysis on logs from that period (use Scenario A for deeper analysis). ``` ### Scenario C: Traffic Aggregation Report ```markdown ## Traffic Aggregation Report — **Zone**: (ZoneId: ) **Analysis Time Period**: – **Total Requests**: | **Total Download Traffic**: MB ### Top 20 Resources by Download Traffic | Domain | URL | Requests | Download Traffic | Avg Size | Cache Hit Rate | |---|---|---|---|---|---| | example.com | /video/intro.mp4 | 1,234 | 456.78 MB | 380 KB | 92% hit | | ... | ... | ... | ... MB | ... KB | ...% | ### Insights - 90% cache hit rate"> - ### Recommendations 1. 2. ``` ## Notes > - Log parsing is performed locally on the client; ensure sufficient disk space for temporary log files. > - Log files for high-traffic domains can be very large; prefer aggregated statistics over line-by-line analysis. > - If origin errors (e.g., 502 concentrated on certain IPs) are found, use `eo-origin-health-check.md` for origin health inspection. > - If anomalous requests are concentrated on a few client IPs, use `../security/ip-threat-blacklist.md` for IP blocking. FILE:references/observability/eo-log-downloader.md # eo-log-downloader Users describe a time range and domain in natural language to automatically retrieve the corresponding offline log download links, eliminating the tedious steps of manually selecting time ranges and domains in the console. ## APIs Involved | Action | Description | |---|---| | DownloadL7Logs | Retrieve L7 offline log download links | | DownloadL4Logs | Retrieve L4 offline log download links | | DescribeAccelerationDomains | List acceleration domains under a zone — used to discover subdomains when user provides a root domain | > **Command usage**: This document only lists API names and workflow guidance. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli`. If no valid credentials are configured in the environment, guide the user to log in first: ```sh tccli auth login ``` > The terminal will print an authorization link after execution and remain blocked until the user completes browser authorization, after which the command ends automatically. > Never ask the user for `SecretId` / `SecretKey`, and do not execute any commands that could expose credential contents. 2. ZoneId must be obtained first. Refer to `../api/zone-discovery.md`. ## Scenario A: Download L7 Logs by Time and Domain **Trigger**: User says "get me the logs for example.com from yesterday afternoon", "download the last 6 hours of logs for example.com", "help me download the logs". ### Workflow **Step 1**: Parse time range - Convert the user's natural language time description to ISO 8601 format start and end times - Example: "yesterday from 2 PM to 4 PM" → `2026-03-24T14:00:00+08:00` to `2026-03-24T16:00:00+08:00` - If the user only says "last N hours", calculate backward from the current time - If the user does not specify a time range, ask for confirmation **Step 2**: Confirm domain - If the user specified a domain, use it directly - If the user did not specify a domain, ask for confirmation (the `Domains` parameter can be omitted to download logs for all domains, but inform the user first) > ⚠️ **Root domain vs subdomain**: The `Domains` parameter requires the **actual acceleration subdomain** (e.g., `www.example.com`, `singapore.example.com`), not the zone root domain (e.g., `example.com`). Logs are recorded per subdomain. > If the user provides a root domain (which matches the `ZoneName` from `DescribeZones`), you must: > 1. Call `DescribeAccelerationDomains` with the `ZoneId` to list all subdomains under the zone > 2. Present the subdomain list to the user and ask which one(s) to download, or omit `Domains` to download all **Step 3**: Retrieve log download links Call `DownloadL7Logs` with: - `StartTime` / `EndTime`: Start and end times parsed in Step 1 - `ZoneIds`: Zone ID - `Domains`: Target subdomain list (optional; omit to get logs for all domains under the zone) - If there are many results, use `Limit` and `Offset` for pagination (default Limit=20, max 300) #### Troubleshooting Empty Results If `Data` is empty, check in order: 1. **Domain mismatch** — Did you pass the zone root domain instead of a subdomain? Remove the `Domains` parameter and retry to see if logs exist for other subdomains 2. **Time too recent** — Offline logs have a delay of approximately 1–2 hours. If the user requested logs for a very recent period, suggest retrying later 3. **No traffic** — The domain may have no actual traffic in the queried time range. Use `DescribeTimingL7AnalysisData` or check the console to confirm 4. **Wrong zone** — If the account has multiple zones, the domain may belong to a different zone. Try `ZoneIds=["*"]` to query across all zones **Step 4**: Organize output Organize the returned log file list into a clickable download link table with directly accessible download links. - The API returns `Size` in **bytes**; convert to human-readable units (KB/MB) in the output table - If the user's intent goes beyond downloading (e.g., "I want to analyze traffic by URL", "which resources use the most bandwidth"), proactively suggest using `eo-log-analyzer.md` for local log parsing and aggregation **Output recommendation**: Present the response as "query parameter summary + download link table" with directly clickable download links. ## Scenario B: Download L4 Logs **Trigger**: User says "download L4 logs", "get me the L4 logs", "download the layer 4 proxy logs". ### Workflow **Step 1**: Parse time range Same as Scenario A Step 1. **Step 2**: Confirm L4 proxy instance - If the user specified a ProxyId, use it directly - If the user did not specify, ask whether to download logs for all L4 instances **Step 3**: Retrieve log download links Call `DownloadL4Logs` with: - `StartTime` / `EndTime`: Start and end times - `ZoneIds`: Zone ID - `ProxyIds`: L4 instance ID list (optional) - Handle pagination (default Limit=20, max 300) **Step 4**: Organize output Same as Scenario A Step 4. **Output recommendation**: Same format as Scenario A, with log type labeled as "L4 logs". ## Output Format ```markdown ## Log Download Links **Zone**: (ZoneId: ) **Domain**: / All domains **Time Range**: – **Log Type**: L7 Access Logs / L4 Proxy Logs | Log File | Size | Log Start Time | Log End Time | Download Link | |---|---|---|---|---| | ... | ... KB/MB | ... | ... | [Download](url) | Total: N log files. ``` ## Notes > - Offline logs have a certain delay (approximately 1–2 hours); logs for very recent time periods may not yet be generated. If results are empty, suggest the user retry later. > - Download links have a limited validity period; please download promptly. > - **Log format**: Offline logs use **JSON Lines** format (one JSON object per line). For field descriptions, see [L7 Access Logs](https://edgeone.ai/document/61300) and [L4 Proxy Logs](https://edgeone.ai/document/61301). For output format customization (CSV, TSV, etc.), see [Customizing Log Output Formats](https://edgeone.ai/document/64485). > - **For further analysis**: If the user wants to analyze log content (anomaly detection, traffic breakdown by URL, per-resource bandwidth, etc.), use `eo-log-analyzer.md` which handles download + local parsing + aggregation automatically. FILE:references/observability/eo-origin-health-check.md # eo-origin-health-check Query the origin status code distribution and origin health ratio for a specified domain or the entire account over a given time range, to quickly determine whether the issue lies with the CDN or the origin server. ## APIs Involved | Action | Description | |---|---| | DescribeTimingL7AnalysisData | Query L7 time-series data (response status code analysis at edge nodes) | | DescribeTimingL7OriginPullData | Query L7 origin-pull time-series data (origin status code distribution, origin traffic/bandwidth) | | DescribeTopL7AnalysisData | Query top N domains/URLs/status codes by request count or traffic — used to discover which domains carry traffic | > **Command usage**: This document only lists API names and workflow guidance. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli`. If no valid credentials are configured in the environment, guide the user to log in first: ```sh tccli auth login ``` > The terminal will print an authorization link after execution and remain blocked until the user completes browser authorization, after which the command ends automatically. > Never ask the user for `SecretId` / `SecretKey`, and do not execute any commands that could expose credential contents. 2. ZoneId must be obtained first. Refer to `../api/zone-discovery.md`. - **Shortcut**: Both `DescribeTimingL7OriginPullData` and `DescribeTimingL7AnalysisData` support `ZoneIds=["*"]` to query account-level aggregated data across all zones. Use this when the user does not specify a particular zone or wants an overview. ## Key API Parameter Notes ### Interval (applies to both DescribeTimingL7OriginPullData and DescribeTimingL7AnalysisData) - ⚠️ **Do NOT use `min` (1-minute) granularity** — it generates excessive data volume and frequently triggers API errors (response size limit exceeded). It also puts unnecessary pressure on the data query cluster. - Recommended granularity by query time range: | Query Time Range | Recommended Interval | Notes | |---|---|---| | ≤ 2 hours | `5min` | Good balance of precision and data volume | | 2–24 hours | `hour` | Suitable for most troubleshooting scenarios | | 1–7 days | `hour` or `day` | Use `hour` if you need to identify anomaly time windows | | > 7 days | `day` | Avoid finer granularity for long ranges | - If a query returns empty or errors with a finer granularity, try a coarser granularity or narrow the time range. ### DescribeTimingL7OriginPullData - `ZoneIds` is **required**. Pass `["*"]` for account-level data, or one or more specific ZoneIds. - `DimensionName` controls grouping: - `origin-status-code-category`: Group by category (1XX/2XX/3XX/4XX/5XX) - `origin-status-code`: Group by exact status code (200, 301, 404, 502, etc.) — useful for pinpointing specific error codes - ⚠️ **`DimensionName` does NOT support `domain`**. You cannot group origin-pull data by domain in a single call. To find which domains have origin errors, use `DescribeTopL7AnalysisData` to get the domain list first, then query each domain individually with the `domain` filter. - **Do NOT** include `Filters` with key `mitigatedByWebSecurity` — this filter is not supported by this API and will cause errors. - The `domain` filter works with both `ZoneIds=["*"]` and specific ZoneIds. The value must be the **actual domain that carries traffic** (typically a subdomain like `www.example.com` or `api.example.com`), not the zone root domain (e.g., `example.com`). If filtering returns empty results, try without the domain filter first to confirm data exists, then check what domains are carrying traffic. #### Troubleshooting Empty Results > This applies to both `DescribeTimingL7OriginPullData` and `DescribeTimingL7AnalysisData`. If a query returns empty `TimingDataRecords` or `Data`, follow these steps in order: 1. **Remove the `domain` filter** and query at zone or account level (`ZoneIds=["*"]`) to confirm data exists in the time range 2. **If zone-level is also empty**, try `ZoneIds=["*"]` (account-level) — the domain may belong to a different zone than expected 3. **If account-level has data but domain filter returns empty**, the domain name may be wrong. Use `DescribeTopL7AnalysisData` with `MetricName=l7Flow_request_domain` to discover which domains actually carry traffic 4. **Use a coarser `Interval`** (e.g., `day` instead of `hour`) — finer granularity with wide time ranges can exceed API response limits 5. **Check the time range** — API data typically has a 5–10 minute delay; avoid querying the most recent 10 minutes ### DescribeTimingL7AnalysisData - `ZoneIds` supports `["*"]` for account-level data. - Use `Filters` with key `statusCode` (Operator: `equals`, Value: `["2XX"]`, `["4XX"]`, `["5XX"]`, etc.) to filter by status code category. Each filter call returns the time-series for that specific category. - ⚠️ **You must make separate calls for each status code category** (2XX, 3XX, 4XX, 5XX). There is no single-call way to get the full breakdown. - The `domain` filter follows the same rules as described above — use the actual traffic-carrying domain, not the zone root domain. - **Response structure**: Returns `Data[].TypeValue[].Sum` for the aggregated count. The per-interval breakdown is in `Data[].TypeValue[].Detail[]` (each with `Timestamp` and `Value`). Do NOT use `Data[].Value[]` — that field does not exist. ### DescribeTopL7AnalysisData - `ZoneIds` supports `["*"]` for account-level data. - `MetricName` (singular, not array) controls the ranking dimension. Key values for origin health check: - `l7Flow_request_domain`: Top domains by request count — **use this to discover all domains with traffic**. - `Limit`: Maximum number of top entries to return (default 10, max 1000). Set to 50+ when scanning for anomalous domains. - Returns `Data[].TypeKey` (grouping key, e.g., AppId) and `Data[].DetailData[]` where each entry has `Key` (the domain name) and `Value` (the count). - This is an **edge-side** metric (not origin-pull), but it serves as the domain discovery step before per-domain origin queries. ## Scenario A: Query Origin Status Code Distribution **Trigger**: User says "check the origin status for example.com", "are there any origin issues", "is the origin healthy", "which domains have origin errors". > This scenario has two sub-flows depending on whether the user asks about a **specific domain** or wants an **account-wide scan**. ### Workflow A1: Specific Domain Origin Health Check Use when the user specifies a domain (e.g., "check origin health for api.example.com"). **Step 1**: Confirm query parameters - Confirm the target domain (must be specified by the user or obtained from context) - Default query range is the last 1 hour; the user may also specify a different time range - Recommend avoiding the most recent 10 minutes (API data has a delay) **Step 2**: Query origin status code distribution Call `DescribeTimingL7OriginPullData` with: - `ZoneIds`: `["*"]` for account-level, or specific ZoneId(s) for targeted query - `DimensionName=origin-status-code-category`: Group by origin status code category (2XX/3XX/4XX/5XX) - `MetricNames=["l7Flow_request_hy"]`: Origin-pull request count - `Interval`: `5min` or `hour` for identifying anomaly periods; `day` for longer time ranges (see Interval guidelines above) - Use the `domain` key in `Filters` to filter for the target subdomain > **Tip**: To identify the exact error codes (e.g., 502 vs 504), make a follow-up call with `DimensionName=origin-status-code`. **Step 3**: Calculate health metrics - Health ratio = 2xx requests / total origin requests × 100% - Anomaly ratio = (4xx + 5xx) requests / total origin requests × 100% - If 5xx ratio > 5%, mark as ⚠️ Anomaly **Output recommendation**: Present as "health score + status code distribution table", with anomaly indicators highlighted. ### Workflow A2: Account-Wide Origin Anomaly Scan Use when the user asks "which domains have origin errors", "are there any origin issues across all domains", or does not specify a particular domain. **Step 1**: Get account-level overview Call `DescribeTimingL7OriginPullData` with: - `ZoneIds=["*"]` - `DimensionName=origin-status-code-category` - `MetricNames=["l7Flow_request_hy"]` - `Interval=day` (or as appropriate for the time range) Calculate overall health metrics. If 4xx + 5xx ratio is low (e.g., < 1%), report healthy and stop. Otherwise proceed to identify anomalous domains. **Step 2**: Discover domains with traffic Call `DescribeTopL7AnalysisData` with: - `MetricName=l7Flow_request_domain` - `ZoneIds=["*"]` - `Limit=50` (or higher if the account has many domains) This returns the top domains ranked by edge request count. Extract the domain list from `Data[].DetailData[].Key`. **Step 3**: Per-domain origin status code check For each domain from Step 2, call `DescribeTimingL7OriginPullData` with: - `ZoneIds=["*"]` - `DimensionName=origin-status-code-category` - `MetricNames=["l7Flow_request_hy"]` - `Filters`: `[{"Key": "domain", "Operator": "equals", "Value": [""]}]` Collect each domain's 2XX/3XX/4XX/5XX counts and calculate error ratios. > ⚠️ This step requires one API call per domain. For large domain lists, consider only checking the top 20–30 domains, or parallelize calls where possible. **Step 4**: Drill down into anomalous domains For domains with error ratio > 5%, make a follow-up call with `DimensionName=origin-status-code` to get the exact error code breakdown (e.g., 404 vs 502 vs 503). **Output recommendation**: Present as "account overview + anomalous domain table (sorted by error ratio descending) + top error codes for the worst domains". ## Scenario B: Quick Fault Root Cause Analysis **Trigger**: User says "is it a CDN issue or an origin issue", "help me troubleshoot the origin failure", "where are the 5xx errors coming from", "is EO the problem or the origin". ### Workflow > ⚠️ **Time alignment**: When comparing edge vs origin data, **always use the same `StartTime`, `EndTime`, and `Interval`** for both `DescribeTimingL7AnalysisData` and `DescribeTimingL7OriginPullData` calls. Mismatched time ranges or granularity will produce misleading comparisons. **Step 1**: Collect edge node status code data Call `DescribeTimingL7AnalysisData` **4 times** (once per status code category) to query edge-to-client response status codes: - `MetricNames=["l7Flow_request"]` - `ZoneIds`: `["*"]` for account-level, or specific ZoneId(s) - `Interval`: use the same granularity as Step 2 (see Interval guidelines above) - `Filters`: include `{"Key": "statusCode", "Operator": "equals", "Value": ["2XX"]}` (repeat for `"3XX"`, `"4XX"`, `"5XX"`) - Optionally add `{"Key": "domain", "Operator": "equals", "Value": [""]}` to `Filters` to scope to a specific subdomain Extract the count for each category from `Data[].TypeValue[].Sum`. **Step 2**: Collect origin status code data Call `DescribeTimingL7OriginPullData` to query origin status codes (single call returns all categories): - `DimensionName=origin-status-code-category` - `MetricNames=["l7Flow_request_hy"]` - `ZoneIds`: same scope as Step 1 - `Interval`: same as Step 1 (must match for accurate comparison) - Optionally filter for a specific subdomain via `domain` in `Filters` Extract the count for each category from `TimingDataRecords[].TypeValue[].Sum` where `TypeKey` is the category (2XX/3XX/4XX/5XX). **Step 3**: Comparative analysis for root cause Compare edge vs origin error counts side by side: **5XX comparison:** | Edge 5XX | Origin 5XX | Preliminary Conclusion | |---|---|---| | High | High (similar count) | 5XX errors originate from the origin server — **origin issue** | | High | Low or zero | 5XX generated by CDN/EO nodes — **CDN issue** | | Zero or low | High | Origin has 5XX but CDN cache/retry absorbs them — **origin issue, CDN mitigates** | **4XX comparison:** | Edge 4XX | Origin 4XX | Preliminary Conclusion | |---|---|---| | High | High (similar count) | 4XX errors originate from the origin (missing resources, auth issues) — **origin issue** | | High | Low or zero | 4XX generated by EO rules (WAF, rate limiting, ACL) — **EO configuration issue** | | Low | High | Origin returns 4XX but CDN cache serves valid responses — **origin issue, CDN mitigates** | **Additional signals:** - If edge has 3XX responses but origin does not, these are typically EO-generated redirects (e.g., HTTP→HTTPS forced redirect). - If edge total ≈ origin total, most requests are being forwarded to origin (low cache hit rate). **Step 4**: Provide root cause conclusion and recommendations - Clearly label as "origin issue", "CDN/EO issue", or "mixed / further investigation needed" - For origin issues: recommend checking origin server logs, resource availability, and backend health - For CDN issues: recommend checking EO security rules, cache configuration, and node status - For deeper analysis: recommend using `eo-log-analyzer.md` for log-level troubleshooting **Output recommendation**: Present the response as "edge vs origin comparison table + root cause conclusion + recommendations". ## Output Format ### Scenario A: Origin Health Inspection Report #### A1: Single Domain Report ```markdown ## Origin Health Inspection — (Last Hours/Days) **Zone**: (ZoneId: ) or "All Zones (account-level)" **Query Time Range**: – **Health Score**: (✅ Healthy / ⚠️ Anomaly Detected / 🔴 Critical Anomaly) ### Origin Status Code Distribution | Status Code Category | Request Count | Ratio | |---|---|---| | 2xx | ... | ...% | | 3xx | ... | ...% | | 4xx | ... | ...% ⚠️ (if > 5%) | | 5xx | ... | ...% ⚠️ (if > 5%) | ### Top Error Codes (if anomaly detected) | Status Code | Request Count | Ratio | |---|---|---| | 502 | ... | ...% | | 404 | ... | ...% | | ... | ... | ... | > Use `DimensionName=origin-status-code` to get exact error code breakdown. ### Quick Root Cause - - Recommendation: ``` #### A2: Account-Wide Anomaly Scan Report ```markdown ## Origin Health Scan — Account Overview (Last Hours/Days) **Query Time Range**: – **Scope**: All Zones (account-level) ### Account-Level Summary | Status Code Category | Request Count | Ratio | |---|---|---| | 2xx | ... | ...% | | 3xx | ... | ...% | | 4xx | ... | ...% ⚠️ (if > 5%) | | 5xx | ... | ...% | ### Anomalous Domains (Error Ratio > 5%) | Domain | Total Requests | 2XX | 4XX | 5XX | Error Ratio | |---|---|---|---|---|---| | xxx.example.com | ... | ... | ... | ... | ...% ⚠️ | | yyy.example.com | ... | ... | ... | ... | ...% ⚠️ | | ... | ... | ... | ... | ... | ... | ### Top Error Code Breakdown (worst domains) **xxx.example.com**: | Status Code | Count | Ratio | |---|---|---| | 404 | ... | ...% | | 502 | ... | ...% | ### Recommendations 1. 2. ``` ### Scenario B: Fault Root Cause Analysis ```markdown ## Fault Root Cause Analysis — (Last Hours) **Query Time Range**: – ### Edge vs Origin Comparison | Metric | Edge Node | Origin | |---|---|---| | Total Requests | ... | ... | | 2XX Count | ... | ... | | 4XX Count | ... | ... | | 5XX Count | ... | ... | | Error Ratio (4XX+5XX) | ...% | ...% | ### Root Cause Conclusion **5XX Analysis**: **4XX Analysis**: **Overall**: <"origin issue" / "CDN/EO issue" / "mixed"> - ### Recommendations 1. 2. ``` ## Common Abnormal Status Code Reference When origin-pull or edge responses contain error status codes, use the following reference to understand the cause and guide troubleshooting. For the full list and detailed troubleshooting steps, see: [Abnormal Status Code Reference](https://edgeone.ai/document/58009) and [4XX/5XX Troubleshooting Guide](https://edgeone.ai/document/67228). ### Standard Status Codes (returned by EO edge nodes) | Status Code | Meaning | Common Cause | |---|---|---| | 400 | Bad Request | Request method not allowed by EdgeOne. See [HTTP Limits](https://edgeone.ai/document/63624) | | 403 | Forbidden | Token authentication failure (rule engine), or compliance interception | | 416 | Range Not Satisfiable | Invalid Range request (e.g., `rangeStart < 0`, `rangeStart > rangeEnd`, or `rangeStart > FileSize`) | | 418 | Config Not Found | Node cannot read domain config — check CNAME, domain binding, or dispatch | | 423 | Request Loop | CDN-Loop detected (loops ≥ 16). See [CDN-Loop](https://edgeone.ai/document/54211) | ### EdgeOne Custom Status Codes (520–599) > ⚠️ Business origins should **avoid using 520–599** status codes to prevent confusion with EO's custom codes. #### Connection & Origin Communication Errors | Status Code | Meaning | Troubleshooting | |---|---|---| | 520 / 550 | Origin connection reset (after request sent) | Origin sent RST after connection was established. Check origin server logs for forced disconnections (overload, firewall) | | 521 / 551 | Origin refused connection (TCP handshake) | Origin sent RST during TCP handshake. Check origin port availability and firewall rules for EO IP ranges | | 522 / 552 | Origin connection timeout (TCP handshake) | Origin did not respond during TCP handshake. Check if origin is down or network path is blocked | | 523 / 553 | Origin DNS resolution failure | Domain-based origin DNS lookup failed. Verify the origin domain's DNS configuration | | 524 / 554 | Origin response timeout | Connection established but origin did not respond in time. Check origin load and processing latency | | 525 / 555 | SSL handshake failure | HTTPS origin SSL handshake failed. Check origin SSL certificate validity, port (443), and protocol compatibility | #### Security & Rule Interception | Status Code | Meaning | Troubleshooting | |---|---|---| | 566 | Managed Rules block | Blocked by [Web Protection — Managed Rules](https://edgeone.ai/document/56828). Check managed rule logs | | 567 | Custom Rules / Rate Limiting / Bot Management block | Blocked by custom rules, rate limiting, or bot management. Review rule conditions and whitelist | #### Platform Errors | Status Code | Meaning | Troubleshooting | |---|---|---| | 545 | Edge Function execution error | Edge function runtime error (e.g., undefined variable). Check function code | | 570 | Platform global rate limit | Hit platform-level rate limit. Contact EdgeOne support | FILE:references/observability/eo-traffic-daily-report.md # eo-traffic-daily-report Periodically query L7/L4 traffic trends and automatically generate Markdown daily reports with bandwidth peaks, request counts, top domains, and top regions. Supports multi-day trend comparison and per-domain multi-dimensional drill-down analysis (country, province, IP, UA, status code, URL path, referer, etc.). ## APIs Involved | Action | Description | |---|---| | DescribeTimingL7AnalysisData | Query L7 time-series traffic/bandwidth/request data | | DescribeTopL7AnalysisData | Query L7 top domains, top regions, and other dimensional ranking data | | DescribeTimingL4Data | Query L4 time-series traffic/bandwidth/connection data | > **Command usage**: This document only lists API names and workflow guidance. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm complete parameters and response descriptions. > For full filter condition documentation, see [Metric Analysis Filter Conditions](https://edgeone.ai/document/56985). ### DescribeTopL7AnalysisData Available Dimensions `MetricName` determines the statistical dimension. Below is the complete dimension list: | Dimension | Traffic MetricName | Request MetricName | Return Value Meaning | |---|---|---|---| | Domain | `l7Flow_outFlux_domain` | `l7Flow_request_domain` | Domain name (e.g. `example.com`) | | Country/Region | `l7Flow_outFlux_country` | `l7Flow_request_country` | ISO 3166-1 alpha-2 country code (e.g. `CN`, `US`) | | Province (Mainland China) | `l7Flow_outFlux_province` | `l7Flow_request_province` | Tencent Cloud province code (see mapping table below) | | Status Code | `l7Flow_outFlux_statusCode` | `l7Flow_request_statusCode` | HTTP status code (e.g. `200`, `404`, `503`) | | URL Path | `l7Flow_outFlux_url` | `l7Flow_request_url` | Request path (e.g. `/api/v1/data`) | | Referer | `l7Flow_outFlux_referers` | `l7Flow_request_referers` | Referer source page | | Client IP | `l7Flow_outFlux_sip` | `l7Flow_request_sip` | Client source IP address | | User-Agent | `l7Flow_outFlux_ua` | `l7Flow_request_ua` | Full UA string | | Device Type | `l7Flow_outFlux_ua_device` | `l7Flow_request_ua_device` | Device type (e.g. Mobile, Desktop) | | Browser Type | `l7Flow_outFlux_ua_browser` | `l7Flow_request_ua_browser` | Browser type (e.g. Chrome, Safari) | | OS | `l7Flow_outFlux_ua_os` | `l7Flow_request_ua_os` | Operating system (e.g. Windows, iOS) | | Resource Type | `l7Flow_outFlux_resourceType` | `l7Flow_request_resourceType` | Resource type (e.g. html, jpg, js) | > **Usage tips**: > - When drilling down into a domain, select dimension combinations as needed — no need to query all dimensions at once > - Common combinations: Country + Province + IP (locate traffic sources), Status Code + URL Path (locate abnormal requests), Referer (analyze traffic entry points), UA (identify client types) ## Data Conventions When processing EdgeOne data analysis API responses and generating reports, the following conventions must be observed: ### Unit Conversion: Base-1000 (SI Standard) EdgeOne uniformly uses **base-1000** (SI standard), consistent with networking/storage industry conventions: | Source Unit | Conversion | Target Unit | |---|---|---| | Byte | ÷ 1,000 | KB | | KB | ÷ 1,000 | MB | | MB | ÷ 1,000 | GB | | bps | ÷ 1,000 | Kbps | | Kbps | ÷ 1,000 | Mbps | | Mbps | ÷ 1,000 | Gbps | > **Never use base-1024**. All traffic and bandwidth values in output reports must use base-1000 conversion. ### Timestamp Left-Alignment Rule API time-series data points use **timestamp left-alignment**: a data point at timestamp `T` represents aggregated data for the interval **[T, T + interval)**. For example, when querying with `day` granularity, timestamp `2026-03-23T00:00:00+08:00` represents the full day of **03-23 (00:00 – next day 00:00)**. ### Full Data vs Post-Mitigation Data L7 access data query APIs (`DescribeTimingL7AnalysisData`, `DescribeTopL7AnalysisData`) **return post-mitigation clean traffic/request counts by default** (i.e., excluding requests blocked/challenged by the Web Security module). - When generating **data reports** (daily, weekly, trend analysis, etc.), provide **complete full data** by including both mitigated and non-mitigated data in `Filters`: ``` --Filters '[{"Key":"mitigatedByWebSecurity","Operator":"equals","Value":["yes","no"]}]' ``` - Only filter by mitigation status when the user explicitly requests clean traffic or blocked traffic only. > `mitigatedByWebSecurity` accepts: `yes` (blocked/challenged by Web Security module), `no` (normal requests not mitigated). > Multiple values within the same filter key use **Or** logic; different filter keys use **And** logic. ### Domain Filtering In `DescribeTimingL7AnalysisData` and `DescribeTopL7AnalysisData`, use the `domain` key in `Filters` to filter data for a specific domain: ``` --Filters '[{"Key":"domain","Operator":"equals","Value":["example.com"]},{"Key":"mitigatedByWebSecurity","Operator":"equals","Value":["yes","no"]}]' ``` > Note: `domain` filter and `mitigatedByWebSecurity` filter must be passed together (different keys use And logic). ### Country/Region Codes The country/region dimension returns [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) standard codes. Common mappings: | Code | Country/Region | Code | Country/Region | Code | Country/Region | |---|---|---|---|---|---| | CN | China | US | United States | JP | Japan | | KR | South Korea | SG | Singapore | DE | Germany | | GB | United Kingdom | FR | France | AU | Australia | | CA | Canada | BR | Brazil | IN | India | | RU | Russia | ID | Indonesia | TH | Thailand | > Refer to the ISO 3166-1 standard for the complete code table. Reports should display both the code and the country name. ### Province Code Mapping (Mainland China) The province dimension returns Tencent Cloud internal province codes (integers) that must be mapped to province names. `-1` indicates overseas. For complete mapping, refer to [Tencent Cloud Region/ISP Mappings](https://www.tencentcloud.com/document/product/228/6316#region.2Fisp-mappings). Common mappings: | Code | Province | Code | Province | Code | Province | Code | Province | |---|---|---|---|---|---|---|---| | -1 | Overseas | 22 | Beijing | 1050 | Shanghai | 4 | Guangdong | | 1442 | Zhejiang | 120 | Jiangsu | 121 | Anhui | 122 | Shandong | | 2 | Fujian | 1135 | Hubei | 1465 | Jiangxi | 1466 | Hunan | | 182 | Henan | 1177 | Hebei | 1051 | Chongqing | 1068 | Sichuan | | 153 | Yunnan | 118 | Guizhou | 173 | Guangxi | 1441 | Hainan | | 86 | Inner Mongolia | 1469 | Shanxi | 1464 | Liaoning | 1445 | Jilin | | 1467 | Heilongjiang | 1468 | Tianjin | 145 | Gansu | 1076 | Ningxia | | 119 | Qinghai | 152 | Xinjiang | | | | | > Reports must map codes to province names; never output raw numeric codes. ### IP Segment Aggregation When querying by client IP (`_sip`) dimension, the top IP list typically contains multiple IPs from the same /24 segment. Reports should include **IP segment aggregation analysis**: - Aggregate IPs sharing the same /24 prefix (first 3 octets) - Show total traffic and IP count per /24 segment - Helps identify NAT gateways, CDN origin IP pools, proxy clusters, etc. ### Adaptive Traffic Unit Display Traffic values in reports should automatically select appropriate units based on magnitude: | Condition | Display Format | Example | |---|---|---| | ≥ 1 GB (10⁹ Byte) | `xx.xx GB` | 10.39 GB | | ≥ 1 MB (10⁶ Byte) | `xxx.xx MB` | 138.44 MB | | ≥ 1 KB (10³ Byte) | `xxx.xx KB` | 716.78 KB | | < 1 KB | `xxx B` | 494 B | ### Large Number Abbreviation by Language Request counts and other large numbers should be abbreviated differently based on the **report language context**: #### Chinese Context (中文语境) Use Chinese numeric units (万 / 亿): | Condition | Display Format | Example | |---|---|---| | ≥ 1 亿 (10⁸) | `x.xx 亿` | 302,000,000 → `3.02 亿` | | ≥ 1 万 (10⁴) | `x.xx 万` | 53,581 → `5.36 万` | | < 1 万 | raw number with comma separator | 8,192 | > **Rules**: > - Always use `万` (10⁴) and `亿` (10⁸) as abbreviation tiers — never use `千` (K) in Chinese reports > - Keep 2 decimal places; trailing zeros may be omitted (e.g. `5.30 万` → `5.3 万`) > - Examples: `1,592,166 次` → `159.22 万次`, `53,581,130 次` → `5,358.11 万次`, `312,000,000 次` → `3.12 亿次` #### English Context Use standard K / M / B suffixes (base-1000): | Condition | Display Format | Example | |---|---|---| | ≥ 1 B (10⁹) | `x.xx B` | 3,020,000,000 → `3.02 B` | | ≥ 1 M (10⁶) | `x.xx M` | 5,358,113 → `5.36 M` | | ≥ 1 K (10³) | `x.xx K` | 53,581 → `53.58 K` | | < 1 K | raw number | 812 | > **Rules**: > - K = 10³, M = 10⁶, B = 10⁹ (base-1000, consistent with SI convention) > - Keep 2 decimal places; trailing zeros may be omitted > - Examples: `1,592,166 requests` → `1,592.17 K`, `5,358,113 requests` → `5.36 M` #### Language Detection - If the user communicates in Chinese or requests a Chinese report → use 万/亿 - If the user communicates in English or requests an English report → use K/M/B - When in doubt, match the language used in the user's most recent message ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli`. If no credentials are configured in the environment, guide the user to log in first: ```sh tccli auth login ``` > The terminal will print an authorization link and block until the user completes browser authorization; the command exits automatically upon success. > Never ask the user for `SecretId` / `SecretKey`, and never execute commands that might expose credential contents. 2. A ZoneId must be obtained first. Refer to `../api/zone-discovery.md`. 3. Obtain the account UIN for report headers by calling: ```sh tccli cam GetUserAppId ``` > The response contains `Uin` (current operator), `OwnerUin` (root account), and `AppId`. > - Use **`OwnerUin`** as the account identifier displayed in reports (this is the Tencent Cloud root account UIN). > - Do **not** use `AppId` (returned in data API responses as `TypeKey`) — it is an internal numeric ID, not the user-facing account identifier. ## Scenario A: Generate a Traffic Daily Report for a Specific Date **Trigger**: The user says "generate yesterday's traffic report", "what was the peak bandwidth in the last 24 hours", "generate the traffic report for 2026-03-20", "analyze which countries/IPs/UAs the traffic for example.com comes from", "show me the status code distribution for this domain". ### Workflow **Step 1**: Determine the report date range - If the user says "yesterday" / "today", automatically calculate the corresponding start and end times (ISO 8601 format) - Default time range is "yesterday 00:00 to 23:59" - `DescribeTimingL7AnalysisData` has approximately 10-minute data delay; avoid querying the most recent 10 minutes **Step 2**: Collect L7 time-series data Call `DescribeTimingL7AnalysisData` to query the following metrics: - `l7Flow_outFlux`: EdgeOne response traffic, in Bytes (for total traffic calculation) - `l7Flow_outBandwidth`: EdgeOne response bandwidth, in bps (for peak bandwidth calculation) - `l7Flow_request`: Access request count, in requests (for total request count) - Recommend using `hour` granularity (`Interval=hour`) to identify peak periods - **Must** include `Filters` for full data (see "Data Conventions > Full Data vs Post-Mitigation Data") **Step 3**: Collect L7 Top data Call `DescribeTopL7AnalysisData` to query: - `l7Flow_outFlux_domain`: Response traffic Top by domain (default Top 10) - `l7Flow_outFlux_country`: Traffic Top by country/region (default Top 5) - Increase `Limit` parameter if the zone has many domains - **Must** include `Filters` for full data (see "Data Conventions > Full Data vs Post-Mitigation Data") **Step 4**: Collect L4 time-series data (if L4 proxy is enabled) Call `DescribeTimingL4Data` to query: - `l4Flow_outBandwidth`: Outbound bandwidth peak - `l4Flow_connections`: Concurrent connections - If the zone does not use L4 proxy, skip this step and note it in the report **Step 5**: Compile and generate the Markdown daily report Organize the above data into a structured report containing: bandwidth peak (with peak period), total request count, top domain table, top region table, and L4 data summary. **Output recommendation**: Output as a complete Markdown document with title, time range, key metric summary, and detailed tables. ### Domain Drill-Down: Multi-Dimensional Traffic Distribution Analysis **Trigger**: After viewing a daily/weekly report, the user requests further analysis of a specific domain's traffic distribution, e.g. "show which countries the traffic for example.com comes from", "analyze the visitor IPs and UAs for this domain", "what abnormal status codes does this domain have". > This sub-workflow is an on-demand extension of Scenario A / B, invoked when the user needs deep analysis of a specific domain. **Step 1**: Confirm drill-down parameters - **Target domain**: Selected from user input or the previous step's top domain ranking - **Time range**: Inherit the current report's time range, or as specified by the user - **Analysis dimensions**: Select based on user needs. Common combinations: | Analysis Purpose | Recommended Dimensions | |---|---| | Traffic source analysis | Country/Region (`_country`) + Province (`_province`) + Client IP (`_sip`) | | Client profiling | User-Agent (`_ua`) + Device Type (`_ua_device`) + Browser (`_ua_browser`) + OS (`_ua_os`) | | Request pattern analysis | Status Code (`_statusCode`) + URL Path (`_url`) + Referer (`_referers`) | | Resource type analysis | Resource Type (`_resourceType`) | | Full profile | All of the above as needed | > No need to query all dimensions at once — select based on user focus. If the user says "full analysis", recommend: Country + Province + IP + UA + Status Code + URL Path + Referer. **Step 2**: Collect Top data by dimension For each selected dimension, call `DescribeTopL7AnalysisData`: - **Must** include both `domain` filter and `mitigatedByWebSecurity` full-data filter in `Filters` - Choose between traffic metrics and request count metrics as needed (typically prioritize traffic metrics `l7Flow_outFlux_*`; supplement with request metrics `l7Flow_request_*` when necessary) - Recommend setting `Limit` to 20; adjust based on user needs - Dimension queries can be executed in parallel for efficiency **Step 3**: Collect domain time-series summary data (optional) Call `DescribeTimingL7AnalysisData` with `domain` filter in `Filters` to query the domain's traffic, bandwidth, and request count totals as core report metrics. **Step 4**: Data post-processing - **Province code mapping**: Convert Tencent Cloud province codes to province names (see "Data Conventions > Province Code Mapping") - **Country code annotation**: Append country names alongside ISO 3166-1 alpha-2 codes - **IP segment aggregation**: Merge IPs in the same /24 segment (see "Data Conventions > IP Segment Aggregation") - **Status code classification**: Group by 2xx/3xx/4xx/5xx categories. Note that EdgeOne uses custom status codes in the 520-599 range (e.g., 566 for managed rule blocks, 567 for custom rule/rate limiting/bot management blocks). See [Abnormal Status Code Reference](https://edgeone.ai/document/58009) for full details - **UA classification**: Identify primary client types (e.g. Dart apps, crawlers, browsers, etc.) **Step 5**: Generate traffic distribution report Output the report following the "Output Format > Domain Drill-Down" template below, including core metrics + per-dimension Top tables + comprehensive insights. ## Scenario B: Multi-Day Trend Comparison **Trigger**: The user says "compare the traffic trend over the last 7 days", "how has bandwidth changed this week vs last week", "what are the daily request counts for the past week". ### Workflow **Step 1**: Determine the comparison time range - Parse the user-described time range and calculate start/end times - `DescribeTimingL7AnalysisData` supports a maximum of 31 days per query **Step 2**: Collect multi-day aggregated data Call `DescribeTimingL7AnalysisData` with `day` granularity (`Interval=day`) to query: - `l7Flow_outFlux`: Daily response traffic (for total and trend calculation) - `l7Flow_outBandwidth`: Daily bandwidth peak - `l7Flow_request`: Daily total requests - **Must** include `Filters` for full data (see "Data Conventions > Full Data vs Post-Mitigation Data") - When not specifying `ZoneIds` (or passing `["*"]`), account-level aggregated data is returned **Step 2.1**: Collect L7 Top data (optional but recommended) Call `DescribeTopL7AnalysisData` to query Top domains by response traffic: - When not specifying `ZoneIds` (or passing `["*"]`), account-level aggregated data is returned; specify individual ZoneIds to filter by zone - **Must** include `Filters` for full data **Step 3**: Calculate trend metrics For each day's data, calculate: - Day-over-day change rate (percentage change compared to previous day) - Week-over-week change rate (if time range exceeds 7 days) - Peak day and trough day markers **Output recommendation**: Output as a trend table including date, bandwidth peak, day-over-day change, total requests, day-over-day change, with peak day and anomaly markers. ## Output Format ### Scenario A: Daily Traffic Report ```markdown ## Traffic Daily Report — **Account**: **Zone**: (ZoneId: ) **Report Time Range**: – ### Key Metrics | Metric | Value | Peak Period | |---|---|---| | L7 Total Response Traffic | x.xx GB | — | | L7 Peak Bandwidth | x.xx Mbps | HH:MM | | L7 Total Requests | x,xxx K / x.xx 万 | — | | L4 Peak Bandwidth | x.xx Mbps | HH:MM | | L4 Peak Concurrent Connections | x,xxx | HH:MM | ### Top N Domains (by Traffic) | Domain | Traffic | Share | |---|---|---| | ... | ... | ... | ### Top 5 Regions (by Traffic) | Region | Traffic | Share | |---|---|---| | ... | ... | ... | ``` ### Domain Drill-Down: Traffic Distribution Analysis ```markdown ## Traffic Distribution Report — **Account**: **Domain**: **Report Date**: () **Data Type**: Full data (including requests mitigated by Web Security) **Unit Conversion**: Base-1000 (SI standard) --- ### Key Metrics | Metric | Value | |---|---| | Total Response Traffic | **xx.xx GB** | --- ### Distribution by Country/Region (Top N) | Rank | Country Code | Country/Region | Traffic | Share | |---|---|---|---|---| | 1 | XX | | xx.xx GB | xx.xx% | | ... | ... | ... | ... | ... | **Analysis**: --- ### Distribution by Province (Mainland China + Overseas) | Rank | Province | Traffic | Share | |---|---|---|---| | 1 | Overseas | xx.xx GB | xx.xx% | | 2 | | xxx.xx MB | x.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Distribution by Client IP (Top N) **IP Segment Aggregation**: | IP Segment | Total Traffic | IP Count | |---|---|---| | x.x.x.0/24 | xxx.xx MB | x IPs | | ... | ... | ... | **IP Details**: | Rank | Client IP | Traffic | Share | |---|---|---|---| | 1 | x.x.x.x | xx.xx MB | x.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Distribution by User-Agent (Top N) | Rank | User-Agent | Traffic | Share | |---|---|---|---| | 1 | | xx.xx GB | xx.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Distribution by Status Code (Top N) **Status Code Category Summary**: | Category | Traffic | Share | Description | |---|---|---|---| | 2xx | xx.xx GB | xx.xx% | Success | | 3xx | xxx.xx MB | x.xx% | Redirect | | 4xx | xxx.xx MB | x.xx% | Client Error | | 5xx | xxx.xx MB | x.xx% | Server Error | **Status Code Details**: | Rank | Status Code | Traffic | Share | |---|---|---|---| | 1 | 200 | xx.xx GB | xx.xx% | | 2 | 304 | xxx.xx MB | x.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Distribution by URL Path (Top N) | Rank | URL Path | Traffic | Share | |---|---|---|---| | 1 | /path/to/resource | xx.xx GB | xx.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Distribution by Referer (Top N) | Rank | Referer | Traffic | Share | |---|---|---|---| | 1 | https://example.com/page | xx.xx GB | xx.xx% | | 2 | (empty Referer) | xxx.xx MB | x.xx% | | ... | ... | ... | ... | **Analysis**: --- ### Comprehensive Insights 1. **Traffic source characteristics**: 2. **Client characteristics**: 3. **Request characteristics**: 4. **Areas of concern**: ``` > **Domain drill-down template usage notes**: > - Dimension sections are optional; include only the dimensions actually queried, omit the rest > - The "Analysis" paragraph after each dimension table is mandatory — do not list data without analysis > - Status code dimension must output both "Category Summary" and "Details" tables > - IP dimension must output both "IP Segment Aggregation" and "IP Details" tables > - "Comprehensive Insights" is mandatory and must synthesize findings across multiple dimensions ### Scenario B: Multi-Day Trend Comparison ```markdown ## Traffic Trend Report — – **Account**: **Report Time Range**: – (UTC+8) **Data Granularity**: Day **Data Type**: Full data (including requests mitigated by Web Security) **Unit Conversion**: Base-1000 (SI standard) --- ### Key Metrics Summary | Metric | Value | |---|---| | L7 Total Response Traffic | **xx.xx GB** | | L7 Peak Bandwidth | **x.xx Mbps** ( ) | | L7 Total Requests | **x,xxx.xx K** | --- ### Daily Traffic Trend | Date | Response Traffic | DoD Change | Peak Bandwidth | DoD Change | Total Requests | DoD Change | Notes | |---|---|---|---|---|---|---|---| | MM-DD (Day) | xx.xx GB | — | x.xx Mbps | — | xxx.xx K / x.xx 万 | — | 📈 Highest traffic day | | MM-DD (Day) | xx.xx GB | ±x.x% | x.xx Mbps | ±x.x% | xxx.xx K / x.xx 万 | ±x.x% | | | ... | ... | ... | ... | ... | ... | ... | | | MM-DD (Day) | xx.xx GB | ±x.x% | x.xx Mbps | ±x.x% | xxx.xx K / x.xx 万 | ±x.x% | 📉 Lowest traffic day | | MM-DD (Day) | xx.xx GB | ±x.x% | x.xx Mbps | ±x.x% | xxx.xx K / x.xx 万 | ±x.x% | ⚠️ Peak bandwidth day | **Trend Analysis**: - - - --- ### Top N Domains (by Response Traffic) | Rank | Domain | Traffic | Share | |---|---|---|---| | 1 | example.com | xx.xx GB | xx.xx% | | 2 | cdn.example.com | xxx.xx MB | x.xx% | | ... | ... | ... | ... | **Domain Analysis**: - - - ``` > **Template usage notes**: > - Date column format: `MM-DD (Day)`, annotate dates according to the timestamp left-alignment rule > - DoD change: first day shows "—", subsequent days calculate `(current - previous) / previous × 100%` > - Notes column markers: 📈 Highest traffic day, 📉 Lowest traffic day, ⚠️ Peak bandwidth day > - Traffic ≥ 1 GB displays as `xx.xx GB`, < 1 GB displays as `xxx.xx MB` > - Request counts use language-appropriate abbreviation: Chinese → 万/亿, English → K/M/B (see "Data Conventions > Large Number Abbreviation by Language") > - Trend analysis and domain analysis are mandatory — provide meaningful interpretation based on the data FILE:references/security/README.md # EdgeOne Security Protection Reference Configuration and operations guide for security policy configuration snapshots, template coverage audits, and domain IP group blocklist identification. ## Quick Decision Tree ``` What does the user want to do? │ ├─ "Generate a security status report for this week" │ "Check the current security configuration" │ └─ → `security-weekly-report.md` 🟢 Low risk · Sequential data collection, output conclusions first with concise snapshot │ ├─ "Which domains don't have a security template" │ "Help me check template coverage" │ └─ → `security-template-audit.md` 🟢 Low risk · List unbound domains, prompt for manual confirmation │ ├─ "Check which IP group in example.com's security policy is a blocklist" │ "Which IP group blocks traffic for this domain" │ └─ → `domain-blacklist-inspector.md` 🟢 Low risk · Read-only query, identify blocklist IP groups │ ├─ "Help me analyze recent attack IP concentration" │ "Block these IPs" "IP ban" │ └─ → `ip-threat-blacklist.md` 🔴 High risk · Mandatory Diff display + double confirmation before write operations, only allowed to write to designated blocklist group │ └─ Not sure which API to call └─ → `../api/api-discovery.md` ``` ## Prerequisites All operations require calling APIs via tccli. Before first use, complete the following: 1. **Tool check** — Read `../api/README.md` to complete tccli installation and credential configuration 2. **Get ZoneId** — Read `../api/zone-discovery.md` to obtain the zone ID ## Files in This Directory | File | Risk Level | Core Trigger Scenario | |---|---|---| | `security-weekly-report.md` | 🟢 Low risk | Periodically generate security configuration snapshots to detect abnormal policy changes | | `security-template-audit.md` | 🟢 Low risk | Audit security policy template coverage, find domains without bound templates | | `domain-blacklist-inspector.md` | 🟢 Low risk | Query security policies associated with a specific domain, identify IP groups serving as blocklists | | `ip-threat-blacklist.md` | 🔴 High risk | Analyze L7 high-concentration threat IPs, execute IP blocklist banning (write operations require double confirmation) | ## Reference Links - [EdgeOne Product Documentation](https://edgeone.ai/document) - [EdgeOne API Documentation](https://edgeone.ai/document/50454) - `../api/README.md` FILE:references/security/domain-blacklist-inspector.md # domain-blacklist-inspector Query the security policies associated with a specified EdgeOne domain, parse IP group references in rules with `action=block`, and output a blocklist IP group mapping report. > **Purpose**: This skill is a **prerequisite diagnostic step** for write operations (such as `eo-ip-threat-blacklist`). Before writing entries to a blocklist IP group, use this skill to identify the correct target blocklist group ID to avoid operating on the wrong IP group. ## APIs Involved | Action | Description | |---|---| | `DescribeSecurityPolicy` | Query the security policy configuration associated with a domain | | `DescribeSecurityIPGroup` | Query all IP groups under the zone | | `DescribeSecurityIPGroupContent` | Query detailed entries of a specified IP group | > **Command usage**: This document only lists API names and process guidelines. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm the complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli` — confirm login authentication is complete before execution. 2. You need to obtain the ZoneId first — see `../api/zone-discovery.md`. 3. The user must explicitly provide the target domain (e.g., `example.com`); if the user says "this domain" without specifying, ask for clarification first. ## Execution Flow **Trigger**: User says "check which IP group in example.com's security policy is a blocklist", "which IP group blocks traffic for this domain", "help me check example.com's IP ban list", "I want to add IPs to the blocklist — first help me identify the blocklist group". Call the following APIs in order to build the blocklist IP group mapping report: ### Step 1: Get the Security Policy Associated with the Domain Call the `DescribeSecurityPolicy` API, extract all rules from the result, identify rules with **blocking or banning semantics** (e.g., `action=block`, `Action.Name=Deny`, etc. — determine based on the actual meaning of field values), and record the IP group IDs referenced by these rules. ### Step 2: Get All IP Groups Under the Zone Call the `DescribeSecurityIPGroup` API, cross-reference the IP group IDs identified in Step 1 with this list to fill in metadata like IP group names. ### Step 3: Query Detailed Entries of Blocklist IP Groups For each blocklist IP group identified in Step 1, call the `DescribeSecurityIPGroupContent` API to query its detailed contents. ### Blocklist IP Group Identification Rules **Use rule action as the primary criterion**: - **Confirmed as blocklist group**: IP groups directly referenced by `action=block` rules in security policies - **Auxiliary reference**: IP group names containing semantic keywords like `blacklist`, `blocklist`, `deny`, or localized equivalents can serve as supplementary evidence, but should not be the sole criterion > ⚠️ **Note**: > - Do not judge solely by IP group name — must verify against rule actions in security policies. > - If multiple IP groups are referenced by `action=block` rules, list them all and explain the rule context for each. > - If determination is unclear, state this honestly and list all IP groups referenced by blocking rules for the user to manually confirm. ## Output Format > **Language note**: Adapt the report language to match the user's language. The template below is an example — output should be in the same language the user is using. ```markdown ## Blocklist IP Group Query Results **Domain**: example.com (ZoneId: zone-xxx) **Query Date**: YYYY-MM-DD **Data Sources**: `DescribeSecurityPolicy` / `DescribeSecurityIPGroup` / `DescribeSecurityIPGroupContent` ### Blocklist IP Groups (Referenced by action=block Rules) > The following IP groups are directly referenced by blocking rules in the security policy — they are the blocklist IP groups for this domain: | IP Group Name | **IP Group ID** | Entry Count | Associated Rule ID | Rule Action | |---|---|---|---|---| | blacklist-prod | **ipg-xxxxxxxx** | 42 | rule-001 | Block | > To write entries to the above IP group, use IP Group ID: `ipg-xxxxxxxx` ### IP Group Detailed Entries **blacklist-prod** (ipg-xxxxxxxx) | # | IP / CIDR | Notes | |---|---|---| | 1 | 1.2.3.4 | ... | | 2 | 5.6.7.8/24 | ... | > If there are more than 20 entries, show the first 20 and note "N total entries, showing first 20". ### Security Policy Associated Rules Summary | Rule ID | Rule Name | Action | Referenced IP Group | Notes | |---|---|---|---|---| | rule-001 | Blocklist Block | Block | blacklist-prod | ... | ### Additional Notes (if any) - Anomalous entry notes (e.g., empty IP group, overly broad CIDR like `0.0.0.0/0`, etc.) - Other noteworthy blocking rules ``` > **Read-only disclaimer**: This skill only performs query operations and does not modify any IP groups or policy configurations. To modify blocklists, use the console or call the appropriate write APIs — confirm the impact scope before operating. FILE:references/security/ip-threat-blacklist.md # ip-threat-blacklist Analyze high-concentration threat IPs based on EdgeOne L7 access data, write them to a designated blocklist IP group, and automate IP banning. ## APIs Involved | Action | Description | |---|---| | `DescribeTopL7AnalysisData` | Query L7 traffic Top data (analyze access concentration by IP dimension) | | `DescribeSecurityIPGroup` | Query the security IP group list under the zone (confirm target blocklist group) | | `ModifySecurityIPGroup` | Modify security IP group entries (write blocklist IPs) | > **Command usage**: This document only lists API names and process guidelines. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm the complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli`. If no valid credentials are configured in the environment, you must first guide the user to complete login: ```sh tccli auth login ``` > After execution, the terminal will print an authorization link and block until the user completes browser authorization — the command ends automatically upon success. > Never ask the user for `SecretId` / `SecretKey`, and do not execute commands that might expose credential contents. 2. You need to obtain the ZoneId first — see `../api/zone-discovery.md`. 3. **Write operation security red lines**: - Before executing `ModifySecurityIPGroup`, you **must** show the complete change Diff to the user and wait for explicit confirmation before executing. - **Only write to the blocklist IP group specified by the user** — never select or create an IP group on your own. - If the user has not explicitly specified a target IP group, guide them to first use `domain-blacklist-inspector.md` to identify the target blocklist group ID before proceeding. ## Scenario A: Analyze High-Concentration Threat IPs **Trigger**: User says "help me analyze recent attack IP concentration", "which IPs have abnormal access volume", "help me check for suspicious IPs". ### Process 1. Confirm the analysis time range (default "last 24 hours"), and explicitly state the start and end time in the report 2. Call the `DescribeTopL7AnalysisData` API, querying Top access data by IP dimension: - Recommended metrics: request count (`l7Flow_request`) or bandwidth (`l7Flow_flux`) - Results are sorted by request volume in descending order, take Top N (default Top 20) 3. Perform concentration analysis on the returned IP list: | Analysis Dimension | Description | |---|---| | Request share | Single IP request count / total requests — a high share (e.g., > 5%) indicates abnormal concentration | | Request rate | Average QPS for a single IP within the time window — significantly exceeding normal levels is suspicious | | Concentration ranking | Gap between Top 1 IP and Top 10 IP request volumes — a large gap suggests a single-point concentrated attack | 4. Output the analysis report, flag suspected threat IPs, and ask the user whether to proceed with banning **Output suggestion**: Respond with "Top IP list + concentration analysis + threat assessment", and at the end prompt the user whether to enter Scenario B for banning. ## Scenario B: Execute IP Blocklist Banning **Trigger**: User says "block these IPs", "IP ban", "add top attack IPs to blocklist". > ⚠️ **This scenario involves write operations — the double confirmation process must be strictly followed and cannot be skipped.** ### Process #### Step 1: Confirm Target Blocklist IP Group 1. Ask the user which blocklist IP group to write to (must be explicitly specified by the user — never decide on your own) 2. If the user is unsure about the target IP group, guide them to first execute `domain-blacklist-inspector.md` to look it up 3. Call the `DescribeSecurityIPGroup` API to query and display the target IP group's current status (name, ID, existing entry count) #### Step 2: Confirm IPs to Be Blocked 1. If the user is coming from Scenario A, use the threat IP list analyzed in Scenario A 2. If the user directly provides an IP list, use it as-is 3. Perform basic validation on the IP list to be blocked: - Format validation: Ensure each entry is a valid IP address or CIDR (e.g., `1.2.3.4` or `1.2.3.0/24`) - Duplicate check: Filter out entries already existing in the target IP group to avoid duplicate writes - Range warning: If large CIDR ranges like `/8` or `/16` exist, specifically alert the user for confirmation #### Step 3: Display Change Diff + Double Confirmation Before executing the write operation, you **must** show the following Diff to the user: ``` The following changes will be applied to the IP group: Target IP group: (ID: ipg-xxxxxxxx) Current entry count: N entries New entries (M total): + 1.2.3.4 + 5.6.7.8 + 9.10.11.0/24 ... Entry count after change: N + M entries ⚠️ This operation takes effect immediately — requests from blocked IPs will be intercepted. Do you want to proceed? (Yes/No) ``` **You must wait for the user to explicitly reply "Yes" or "Confirm" before calling `ModifySecurityIPGroup`.** #### Step 4: Execute Write and Verify 1. Call the `ModifySecurityIPGroup` API to write the new IPs to the target blocklist group 2. After writing, call `DescribeSecurityIPGroup` again to query the target IP group and verify the entry count matches expectations 3. Output the operation result summary ## Scenario C: Query Current Blocklist IP Group Status **Trigger**: User says "check what IPs are in the blocklist", "how many entries are in the blocklist group now". Call the `DescribeSecurityIPGroup` API to query and display the current entry list of the specified IP group. > To find the blocklist IP group ID associated with a domain, see `domain-blacklist-inspector.md`. ## Output Format > **Language note**: Adapt the report language to match the user's language. The templates below are examples — output should be in the same language the user is using. ### Scenario A: Threat IP Analysis Report ```markdown ## Threat IP Concentration Analysis Report **Zone**: example.com (ZoneId: zone-xxx) **Analysis Time Range**: 2026-03-16 00:00 – 2026-03-23 00:00 **Data Source**: `DescribeTopL7AnalysisData` (Metric: request count) ### Top IP Access Ranking | Rank | IP Address | Request Count | Share of Total | Avg QPS | Threat Assessment | |---|---|---|---|---|---| | 1 | 1.2.3.4 | 1,200,000 | 12.5% | 1,984/s | 🔴 High risk | | 2 | 5.6.7.8 | 800,000 | 8.3% | 1,322/s | 🔴 High risk | | 3 | 9.10.11.12 | 200,000 | 2.1% | 330/s | 🟡 Suspicious | | ... | ... | ... | ... | ... | ... | ### Concentration Analysis - Total requests: 9,600,000 - Top 1 IP share: 12.5% (exceeds 5% threshold — abnormally concentrated) - Top 3 IPs combined share: 22.9% - Concentration assessment: **Clear signs of single-point concentrated attack** ### Suggested IPs to Block The following IPs have request share exceeding the threshold or abnormal QPS — recommended for blocklist: - `1.2.3.4` (share 12.5%, QPS 1,984/s) - `5.6.7.8` (share 8.3%, QPS 1,322/s) > To add the above IPs to the blocklist, specify the target blocklist IP group, or reply "block" to proceed. ``` ### Scenario B: Banning Operation Result ```markdown ## IP Blocklist Write Result **Target IP Group**: blacklist-prod (ID: ipg-xxxxxxxx) **Operation Time**: 2026-03-23 19:00:00 **Data Source**: `ModifySecurityIPGroup` ### Change Summary | Item | Count | |---|---| | New entries added | 2 | | Skipped (already exist) | 0 | | Total entries after operation | 44 | ### New Entry Details | IP / CIDR | Source | Notes | |---|---|---| | 1.2.3.4 | Top L7 analysis | Request share 12.5% | | 5.6.7.8 | Top L7 analysis | Request share 8.3% | ### Verification Result ✅ Write successful — IP group currently has 44 entries, matching expectations. ``` ## Important Notes > ⚠️ **Operation safety notice**: > - `ModifySecurityIPGroup` is a **full overwrite** API — when calling it, you must pass the complete entry list of the IP group (existing entries + new entries), not just the new entries. Always query existing entries first, merge them, then write — **never overwrite directly and lose existing entries**. > - Banning takes effect immediately — requests from banned IPs will be intercepted in real time. Execute only after confirming threat IPs. > - For bulk banning of many IPs (e.g., more than 50), prefer writing a script for one-time execution to avoid omissions from multiple calls. FILE:references/security/security-template-audit.md # security-template-audit Audit EdgeOne security policy template coverage, output template-to-bound-resource mappings, and find domains without any bound templates — suitable for security audit scenarios. ## APIs Involved | Action | Description | |---|---| | `DescribeWebSecurityTemplates` | Query all security policy templates under the zone | | `DescribeWebSecurityTemplate` | Query detailed configuration of a single template | | `DescribeSecurityTemplateBindings` | Query the binding relationship between templates and domains | > **Command usage**: This document only lists API names and process guidelines. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm the complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli` — confirm login authentication is complete before execution. 2. You need to obtain the ZoneId first — see `../api/zone-discovery.md`. ## Execution Flow **Trigger**: User says "which domains don't have a security template", "help me check template coverage", "are there any domains that missed binding a security policy", "help me audit security templates", "which domains have no security protection", "what's the template binding status", "help me check security templates", "are there domains without bound templates". Call the following APIs in order to progressively build the template-binding resource mapping: ### Step 1: Get All Security Policy Templates Call the `DescribeWebSecurityTemplates` API, record each template's `TemplateId` and `TemplateName` as input for subsequent queries. ### Step 2: Get Detailed Configuration for Each Template Call the `DescribeWebSecurityTemplate` API, focusing on the following fields for subsequent status labeling: - Whether the template is enabled (overall toggle status) - Whether each protection module (WAF, CC, Bot, etc.) has rule configurations ### Step 3: Query Domain Binding Relationships for Each Template Call the `DescribeSecurityTemplateBindings` API, collect the list of domains bound to each template, and aggregate into a global "covered domains set". ### Step 4: Get the Complete Domain List for the Zone To identify uncovered domains, you need the complete domain list under the zone — call the `DescribeZoneRelatedDomains` API. > If this API is unavailable or returns empty, try finding other APIs to get the domain list (such as `DescribeAccelerationDomains`) via `../api/api-discovery.md`. ### Step 5: Cross-Compare to Identify Uncovered Domains Compute the difference between the "covered domains set" (aggregated from Step 3) and the complete zone domain list to produce the list of domains not bound to any template. > ⚠️ **Note**: If the complete domain list cannot be obtained, explicitly state "currently can only output known coverage based on template binding relationships — cannot confirm whether there are missing domains" — do not make assumptions. ## Output Format > **Language note**: Adapt the report language to match the user's language. The template below is an example — output should be in the same language the user is using. ```markdown ## Security Template Coverage Audit Report **Zone**: example.com (ZoneId: zone-xxx) **Audit Date**: YYYY-MM-DD **Data Sources**: `DescribeWebSecurityTemplates` / `DescribeWebSecurityTemplate` / `DescribeSecurityTemplateBindings` ### Template-Binding Resource Mapping | Template Name | Template ID | Bound Domains Count | Bound Domain List | Template Status | |---|---|---|---|---| | Production Template | template-xxx | 3 | a.com, b.com, c.com | ✅ Normal | | Test Template | template-yyy | 0 | — (no domains bound) | ⚠️ Empty template | ### Coverage Summary - Total templates: N - Templates with bound domains: N / Empty templates (no domains bound): N - Total covered domains: N - **Uncovered domains: N** ### Uncovered Domain List > The following domains are not bound to any security policy template and have a protection gap: - example.com - test.example.com - staging.example.com (If the complete domain list is unavailable, note here: "Data is incomplete, showing known coverage only") ### Recommended Actions - Uncovered domains: Evaluate and bind an appropriate security template - Empty templates: Confirm whether they are reserved templates; consider cleanup if unused ``` > **Read-only disclaimer**: This skill only performs query operations and does not perform any binding or modification. To bind templates, use the console or call the appropriate write APIs — confirm the impact scope before operating. FILE:references/security/security-weekly-report.md # security-weekly-report Manage the security protection status of EdgeOne zones: generate configuration snapshots, detect abnormal policy changes, and produce security reports. ## APIs Involved | Action | Description | |---|---| | `DescribeSecurityPolicy` | Query the zone's security policy configuration | | `DescribeWebSecurityTemplates` | Query all security policy templates under the zone | | `DescribeSecurityIPGroup` | Query the security IP group list | > **Command usage**: This document only lists API names and process guidelines. > Before execution, consult the API documentation via `../api/api-discovery.md` to confirm the complete parameters and response descriptions. ## Prerequisites 1. All Tencent Cloud API calls are executed via `tccli`. If no valid credentials are configured in the environment, you must first guide the user to complete login: ```sh tccli auth login ``` > After execution, the terminal will print an authorization link and block until the user completes browser authorization — the command ends automatically upon success. > Never ask the user for `SecretId` / `SecretKey`, and do not execute commands that might expose credential contents. 2. You need to obtain the ZoneId first — see `../api/zone-discovery.md`. ## Scenario A: Generate Current Security Configuration Snapshot **Trigger**: User says "check the current security configuration", "help me compile a security policy snapshot for this zone". For the same `ZoneId`, call the following 3 APIs in sequence: `DescribeSecurityPolicy`, `DescribeWebSecurityTemplates`, `DescribeSecurityIPGroup`. **Output suggestion**: Respond with "current snapshot + risk alerts", appending a concise JSON snapshot at the end (see appendix format) for future report comparisons. ## Scenario B: Generate Security Protection Report **Trigger**: User says "generate a security status report for this week", "check if there have been any security policy changes recently". ### Process 1. Confirm the time range (default "this week"), and explicitly state the start and end time in the report 2. Call the 3 APIs from Scenario A in sequence to collect the current configuration 3. If the user provides a historical baseline (last week's report, old snapshot, or historical results from the conversation), perform a diff comparison: | Comparison Dimension | Description | |---|---| | Additions | Policies, templates, IP groups added this week | | Deletions | Configurations deleted or unbound this week | | Modifications | Configuration items changed this week | | Risk escalation | Protection capabilities disabled, policies downgraded from block to observe, etc. | | Risk de-escalation | Protection capabilities restored, policies tightened, etc. | 4. If **no historical snapshot is available**, explicitly state "only a configuration snapshot can be generated at this time — cannot determine whether changes are abnormal", and output the current result as the new baseline snapshot **Output suggestion**: Structure the output as "Report scope → Current configuration summary → This week's changes & risks → Recommended actions → Appendix snapshot" (see output format). ## Scenario C: Risk Inspection **Trigger**: User says "help me check if there are security configuration issues", "are there any high-risk configurations". After completing the data collection from Scenario A, highlight the following anomalies: - Critical protection capabilities disabled - Policies downgraded from block to observe or off - Overly broad allow configurations - Security templates unbound or in abnormal status - IP groups empty, containing overly broad CIDR ranges, or test groups active long-term > ⚠️ **Note**: Do not declare "abnormal changes" without evidence — you must provide evidence from the current configuration or historical snapshot. ## Output Format > **Language note**: Adapt the report language to match the user's language. The template below is an example — output should be in the same language the user is using. ```markdown ## Security Protection Report **Zone**: example.com (ZoneId: zone-xxx) **Time Range**: 2026-03-13 – 2026-03-19 **Data Sources**: `DescribeSecurityPolicy` / `DescribeWebSecurityTemplates` / `DescribeSecurityIPGroup` ### Current Configuration Summary - Core protection capability status: ... - Template binding summary: ... - IP group summary: ... ### This Week's Changes & Risks - Configuration changes found this week: ... - Suspected abnormal changes: ... - Items requiring manual confirmation: ... ### Recommended Actions - Immediate action: ... - Action within this week: ... - Continue monitoring: ... ``` ### Appendix: Concise JSON Snapshot Append the following format snapshot at the end of the report, for future report comparisons: ```json { "zoneId": "", "generatedAt": "", "timeRange": { "start": "", "end": "" }, "securityPolicy": {}, "webSecurityTemplates": [], "securityIPGroups": [] } ```

Tencent EdgeOne

Comments (0)