diff --git a/docs/docs.json b/docs/docs.json index 9954521838..b4db492ea5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -310,7 +310,10 @@ "pages": [ "enterprise-solutions/monitoring/overview", "enterprise-solutions/monitoring/telemetry", - "enterprise-solutions/monitoring/opentelemetry" + "enterprise-solutions/monitoring/prompt-storage", + "enterprise-solutions/monitoring/opentelemetry", + "enterprise-solutions/monitoring/opentelemetry-events", + "enterprise-solutions/monitoring/opentelemetry_override" ] }, "enterprise-solutions/api-reference" diff --git a/docs/enterprise-solutions/monitoring/opentelemetry-events.mdx b/docs/enterprise-solutions/monitoring/opentelemetry-events.mdx new file mode 100644 index 0000000000..6b124faa57 --- /dev/null +++ b/docs/enterprise-solutions/monitoring/opentelemetry-events.mdx @@ -0,0 +1,630 @@ +--- +title: "OpenTelemetry Events Reference" +sidebarTitle: "OTel Events" +description: "Complete reference of OpenTelemetry log events emitted by Cline" +--- + +This page documents all OpenTelemetry log events currently instrumented in Cline. These events are emitted when OpenTelemetry integration is enabled and provide detailed insights into user behavior, task execution, and system operations. + + +Events are only emitted when OpenTelemetry is enabled. See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for configuration instructions. + + +## Event Categories + +Cline emits events across several categories, each prefixed with a namespace: + + + + Authentication, telemetry controls, extension lifecycle + + + + Task execution, conversation turns, tool usage, tokens + + + + Workspace initialization, VCS detection, path resolution + + + + User interface interactions and model selection + + + + Hook discovery, execution, and context modification + + + + Git worktree operations and merge handling + + + + Host environment detection + + + + Diagnostic and connection testing + + + +## User Events + +Events related to user authentication, telemetry preferences, and extension lifecycle. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `user.opt_out` | User explicitly opts out of telemetry | user_id, timestamp | +| `user.opt_in` | User explicitly opts into telemetry | user_id, timestamp | +| `user.telemetry_enabled` | Telemetry service enabled/initialization signal | enabled, timestamp | +| `user.extension_activated` | Extension activation event | extension_version, host_type | +| `user.extension_storage_error` | Error while reading/writing extension storage state | error_type, error_message | +| `user.auth_started` | Authentication flow started | provider, timestamp | +| `user.auth_succeeded` | Authentication flow succeeded | provider, user_id | +| `user.auth_failed` | Authentication flow failed | provider, error_reason | +| `user.auth_logged_out` | User logged out | reason, provider | +| `user.onboarding_progress` | Onboarding step/action progress | step, action, completed | + +### Example: user.auth_succeeded + +```json +{ + "event": "user.auth_succeeded", + "timestamp": "2026-03-05T10:30:00Z", + "attributes": { + "provider": "github", + "user_id": "user_abc123", + "session_id": "sess_xyz789" + } +} +``` + +## Workspace Events + +Events related to workspace initialization, version control detection, and multi-root operations. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `workspace.initialized` | Workspace initialization completed | roots_count, vcs_type, duration_ms | +| `workspace.init_error` | Workspace initialization failed | error_type, fallback_used | +| `workspace.vcs_detected` | Version control system detection event | vcs_type, root_path_hash | +| `workspace.multi_root_checkpoint` | Multi-root checkpoint operation telemetry | operation, roots_count, duration_ms | +| `workspace.path_resolved` | Workspace path resolution | hint, fallback_used, cross_workspace | + +### Example: workspace.initialized + +```json +{ + "event": "workspace.initialized", + "timestamp": "2026-03-05T10:32:15Z", + "attributes": { + "roots_count": 2, + "vcs_type": "git", + "duration_ms": 145, + "multi_root_enabled": true + } +} +``` + +## Task Events + +Core events tracking task lifecycle, conversation turns, tool usage, and execution details. + +### Task Lifecycle + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.created` | New task/conversation started | task_id, mode, model, provider | +| `task.restarted` | Existing task restarted/reopened | task_id, time_since_last_message | +| `task.completed` | Task completed | task_id, duration_ms, model, provider, tokens_total | +| `task.feedback` | User feedback on task | task_id, feedback_type (thumbs_up/thumbs_down) | +| `task.historical_loaded` | Historical task loaded from storage | task_id, age_days | +| `task.retry_clicked` | User clicked retry on a failed action/request | task_id, action_type | + +### Conversation & Tokens + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.conversation_turn` | Conversation turn event | role (user/assistant), provider, model, tokens_in, tokens_out | +| `task.tokens` | Token usage event | tokens_in, tokens_out, cached_tokens, cost | +| `task.mode` | Plan/Act mode switch event | previous_mode, new_mode, task_id | + +### Tool Usage + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.tool_used` | Tool invocation and outcome telemetry | tool_name, success, duration_ms, auto_approved | +| `task.mcp_tool_called` | MCP tool call lifecycle event | status (started/success/error), tool_name, server_name | +| `task.browser_tool_start` | Browser tool/session started | url, action | +| `task.browser_tool_end` | Browser tool/session ended with stats | duration_ms, actions_count, success | +| `task.browser_error` | Browser tool error event | error_type, url | +| `task.terminal_execution` | Terminal execution capture success/failure event | success, command_hash, duration_ms | +| `task.terminal_output_failure` | Terminal output capture failed | reason | +| `task.terminal_user_intervention` | User intervention during terminal execution | intervention_type | +| `task.terminal_hang` | Terminal hang/stuck detection event | duration_ms, command_hash | + +### Features & Options + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.checkpoint_used` | Checkpoint action used | action (create/restore/compare), task_id | +| `task.option_selected` | User selected one of AI-provided options | option_index, total_options | +| `task.options_ignored` | User ignored AI options and entered custom input | options_count | +| `task.slash_command_used` | Slash command/workflow/MCP prompt command used | command_name, is_workflow | +| `task.mention_used` | Mention resolution succeeded | mention_type (file/url/folder/terminal/problems/git) | +| `task.mention_failed` | Mention resolution failed | mention_type, error_reason | +| `task.mention_search_results` | Mention search query result telemetry | query, results_count | +| `task.workspace_search_pattern` | Workspace search strategy/pattern telemetry | pattern_type, files_scanned | + +### Advanced Features + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.focus_chain_enabled` | Focus chain feature enabled | task_id | +| `task.focus_chain_disabled` | Focus chain feature disabled | task_id | +| `task.focus_chain_progress_first` | First focus-chain checklist/progress emitted | items_count | +| `task.focus_chain_progress_update` | Subsequent focus-chain checklist/progress updates | items_total, items_completed | +| `task.focus_chain_incomplete_on_completion` | Task completed while focus-chain checklist still incomplete | items_remaining | +| `task.focus_chain_list_opened` | Focus-chain markdown/list opened by user | task_id | +| `task.focus_chain_list_written` | Focus-chain markdown/list written/saved | task_id | +| `task.subagent_enabled` | Subagents feature enabled | task_id | +| `task.subagent_disabled` | Subagents feature disabled | task_id | +| `task.subagent_started` | Subagent execution started | subagent_id, prompt_length | +| `task.subagent_completed` | Subagent execution completed | subagent_id, duration_ms, success | +| `task.skill_used` | Skill invocation event | skill_name, task_id | + +### Auto-Compact & Context + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.summarize_task` | Auto-compaction/summarize triggered for context pressure | conversation_length, estimated_tokens | +| `task.auto_condense_toggled` | Auto-condense setting toggled | enabled | + +### Settings & Features + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.feature_toggled` | Generic feature toggle changed | feature_name, enabled | +| `task.rule_toggled` | Cline rule toggled on/off | rule_name, enabled, is_global | +| `task.yolo_mode_toggled` | YOLO mode toggled | enabled | +| `task.cline_web_tools_toggled` | Cline web tools setting toggled | enabled | + +### API & Performance + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.gemini_api_performance` | Gemini-specific API performance telemetry | duration_ms, tokens, cache_hit | +| `task.provider_api_error` | API provider error event | provider, model, error_code, error_message | +| `task.diff_edit_failed` | Diff/replace edit failed | file_path_hash, error_type | +| `task.initialization` | Task initialization timing/metadata event | duration_ms, mode | + +### AI Output Feedback + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `task.ai_output.accepted` | AI-generated file edit accepted | lines_added, lines_removed, file_count | +| `task.ai_output.rejected` | AI-generated file edit rejected | lines_added, lines_removed, file_count | + +### Example: task.tool_used + +```json +{ + "event": "task.tool_used", + "timestamp": "2026-03-05T10:35:22Z", + "attributes": { + "task_id": "task_1234567890", + "tool_name": "write_to_file", + "success": true, + "duration_ms": 125, + "auto_approved": false, + "model": "claude-sonnet-4", + "provider": "anthropic" + } +} +``` + +## UI Events + +Events tracking user interface interactions. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `ui.model_selected` | Model selected in UI | model, provider, previous_model | +| `ui.model_favorite_toggled` | Model favorite toggled | model_id, is_favorited | +| `ui.button_clicked` | UI button click event | button_id, context | +| `ui.rules_menu_opened` | Rules/workflows menu/modal opened | menu_type | + +### Example: ui.model_selected + +```json +{ + "event": "ui.model_selected", + "timestamp": "2026-03-05T11:20:00Z", + "attributes": { + "model": "claude-sonnet-4", + "provider": "anthropic", + "previous_model": "gpt-4o", + "mode": "act" + } +} +``` + +## Hooks Events + +Events related to hook discovery, execution lifecycle, and context modifications. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `hooks.enabled` | Hooks feature enabled | user_id | +| `hooks.disabled` | Hooks feature disabled | user_id | +| `hooks.cancel_requested` | Hook requested cancellation | hook_name, task_id | +| `hooks.context_modified` | Hook modified context | hook_name, modification_type | +| `hooks.discovery_completed` | Hook discovery completed | hooks_count, global_count, workspace_count | +| `hooks.execution` | Unified hook execution lifecycle | hook_name, status (started/completed/failed/cancelled), duration_ms | + +### Hook Execution Lifecycle + +The `hooks.execution` event tracks the complete lifecycle with a `status` attribute: + +- **started**: Hook execution began +- **completed**: Hook finished successfully +- **failed**: Hook encountered an error +- **cancelled**: Hook was cancelled by user or system + +### Example: hooks.execution + +```json +{ + "event": "hooks.execution", + "timestamp": "2026-03-05T10:40:15Z", + "attributes": { + "hook_name": "preToolUse", + "status": "completed", + "duration_ms": 234, + "task_id": "task_1234567890", + "context_modified": false + } +} +``` + +## Worktree Events + +Events related to Git worktree operations. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `worktree.view_opened` | Worktree view opened | user_id | +| `worktree.created` | Worktree create event | success, branch_name, duration_ms | +| `worktree.merge_attempted` | Worktree merge attempt event | has_conflicts, delete_option_chosen | + +### Example: worktree.created + +```json +{ + "event": "worktree.created", + "timestamp": "2026-03-05T14:22:00Z", + "attributes": { + "success": true, + "branch_name_hash": "abc123", + "duration_ms": 1250, + "parent_branch": "main" + } +} +``` + +## Host Events + +Events related to host environment detection. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `host.detected` | Host environment detection event | host_type (vscode/jetbrains/cli), version | + +### Example: host.detected + +```json +{ + "event": "host.detected", + "timestamp": "2026-03-05T09:00:00Z", + "attributes": { + "host_type": "vscode", + "version": "1.95.0", + "platform": "darwin" + } +} +``` + +## Test Events + +Diagnostic and connection testing events. + +| Event | Description | Key Attributes | +|-------|-------------|----------------| +| `cline.test.connection` | OTEL connection test event from "Test OTEL Connection" flow | success, exporter_type, endpoint | + +### Example: cline.test.connection + +```json +{ + "event": "cline.test.connection", + "timestamp": "2026-03-05T15:30:00Z", + "attributes": { + "success": true, + "exporter_type": "otlp", + "endpoint": "https://api.datadoghq.com:4317", + "protocol": "grpc" + } +} +``` + +## Event Attribute Guidelines + +### Common Attributes + +Most events include these standard attributes: + +| Attribute | Type | Description | +|-----------|------|-------------| +| `timestamp` | ISO 8601 | Event occurrence time | +| `user_id` | string | Anonymized user identifier (when authenticated) | +| `session_id` | string | Current session identifier | +| `extension_version` | string | Cline extension version | +| `host_type` | string | vscode, jetbrains, or cli | + +### Privacy & Hashing + +Sensitive information is hashed or anonymized: + +- **File paths**: Hashed to preserve privacy +- **Command content**: Hashed, not logged verbatim +- **User identifiers**: Anonymized tokens +- **Branch names**: Hashed in worktree events + + +File paths, command arguments, and code content are **never** included in raw form. Only hashes or anonymized identifiers are used. + + +## Task Event Deep Dive + +Task events are the most detailed category. Here's a typical task execution flow: + +```mermaid +sequenceDiagram + participant User + participant Cline + participant OTel + + User->>Cline: Start Task + Cline->>OTel: task.created + + User->>Cline: Submit Message + Cline->>OTel: task.conversation_turn (user) + + Cline->>Cline: Process with AI + Cline->>OTel: task.tokens + Cline->>OTel: task.conversation_turn (assistant) + + Cline->>Cline: Use Tool + Cline->>OTel: task.tool_used + + User->>Cline: Provide Feedback + Cline->>OTel: task.option_selected + + User->>Cline: Complete Task + Cline->>OTel: task.completed +``` + +### Task Token Tracking + +Token events provide detailed cost and usage information: + +```json +{ + "event": "task.tokens", + "timestamp": "2026-03-05T10:35:30Z", + "attributes": { + "task_id": "task_1234567890", + "tokens_in": 2500, + "tokens_out": 850, + "cached_tokens": 1200, + "cost": 0.0043, + "model": "claude-sonnet-4", + "provider": "anthropic" + } +} +``` + +## Using Events for Analytics + + +**SQL syntax is illustrative only.** Attribute access varies by observability platform — for example, `JSON_EXTRACT(attributes, '$.model')` in BigQuery, `attributes['model']` in ClickHouse, or `@attributes.model` in Datadog. Adapt all queries below to your platform's query language before use. + + +### Query Patterns + +**Most used tools:** +```sql +SELECT attributes.tool_name, COUNT(*) as count +FROM otel_logs +WHERE event = 'task.tool_used' + AND attributes.success = true +GROUP BY attributes.tool_name +ORDER BY count DESC +LIMIT 10 +``` + +**Average task duration by model:** +```sql +SELECT + attributes.model, + AVG(attributes.duration_ms) as avg_duration_ms, + COUNT(*) as task_count +FROM otel_logs +WHERE event = 'task.completed' +GROUP BY attributes.model +``` + +**Token usage by provider:** +```sql +SELECT + attributes.provider, + SUM(attributes.tokens_in) as total_tokens_in, + SUM(attributes.tokens_out) as total_tokens_out, + SUM(attributes.cost) as total_cost +FROM otel_logs +WHERE event = 'task.tokens' + AND timestamp >= NOW() - INTERVAL '30 days' +GROUP BY attributes.provider +``` + +**Tool approval rates:** +```sql +SELECT + attributes.tool_name, + SUM(CASE WHEN attributes.auto_approved THEN 1 ELSE 0 END)::float / COUNT(*) as auto_approval_rate, + COUNT(*) as total_uses +FROM otel_logs +WHERE event = 'task.tool_used' +GROUP BY attributes.tool_name +ORDER BY total_uses DESC +``` + +## Integration Examples + + +Query syntax below is illustrative. Attribute access varies by platform — for example, `JSON_EXTRACT(attributes, '$.model')` in BigQuery, `attributes['model']` in ClickHouse, or dot notation in Datadog. Adapt to your platform's query language. + + +### Datadog Dashboard + +Create custom Datadog dashboards using these events: + +```json +{ + "widgets": [ + { + "definition": { + "type": "timeseries", + "requests": [ + { + "q": "sum:cline.task.completed{*}.as_count()", + "display_type": "bars" + } + ], + "title": "Tasks Completed Over Time" + } + }, + { + "definition": { + "type": "query_value", + "requests": [ + { + "q": "sum:cline.task.tokens{*}", + "aggregator": "sum" + } + ], + "title": "Total Tokens Used" + } + } + ] +} +``` + +### Grafana Queries + +Example Loki query for tool usage: + +```logql +{event="task.tool_used"} +| json +| line_format "{{.attributes_tool_name}}: {{.attributes_success}}" +``` + +### New Relic NRQL + +Query task completion rates: + +```sql +SELECT count(*) +FROM Log +WHERE event = 'task.completed' +FACET attributes.model +SINCE 1 day ago +``` + +## Event Schema Reference + +All events follow this structure: + +```typescript +interface OtelLogEvent { + event: string // Event name (e.g., "task.created") + timestamp: string // ISO 8601 timestamp + attributes: { + // Event-specific attributes + [key: string]: string | number | boolean + } + resource: { + service_name: "cline" + service_version: string // Extension version + host_type: string // vscode | jetbrains | cli + } +} +``` + +## Best Practices + + + + Focus on events relevant to your use case. Not all events need dashboards. + + + + Alert on error events and usage anomalies for proactive monitoring. + + + + Roll up events into metrics for long-term trend analysis. + + + + Remember events are already anonymized. Don't attempt to de-anonymize. + + + +## Troubleshooting + +### Events Not Appearing + +If events aren't showing up in your observability platform: + +1. **Verify OTel is enabled** in remote configuration or environment variables +2. **Check endpoint configuration** - ensure URL and protocol are correct +3. **Validate credentials** - test with the "Test OTEL Connection" button +4. **Check exporter settings** - ensure logs exporter includes `otlp` +5. **Review platform-specific requirements** - some platforms need specific headers + +### Event Volume Concerns + +If you're seeing excessive event volume: + +1. **Sample events** - Configure sampling in your OTel collector +2. **Filter events** - Use your platform's filtering to drop noisy events +3. **Aggregate on collection** - Pre-aggregate metrics before export +4. **Adjust export intervals** - Increase `openTelemetryMetricExportInterval` and batch settings + +## See Also + + + + Configure OTel integration + + + + Backup conversation history + + + + Basic telemetry overview + + diff --git a/docs/enterprise-solutions/monitoring/opentelemetry.mdx b/docs/enterprise-solutions/monitoring/opentelemetry.mdx index d501c37a3a..f5c967f8ad 100644 --- a/docs/enterprise-solutions/monitoring/opentelemetry.mdx +++ b/docs/enterprise-solutions/monitoring/opentelemetry.mdx @@ -194,7 +194,11 @@ Current OpenTelemetry support in Cline: ## Next Steps - + + + Complete catalog of all emitted OTel events + + Configure simple built-in telemetry diff --git a/docs/enterprise-solutions/monitoring/overview.mdx b/docs/enterprise-solutions/monitoring/overview.mdx index b930879b83..0ad5329b22 100644 --- a/docs/enterprise-solutions/monitoring/overview.mdx +++ b/docs/enterprise-solutions/monitoring/overview.mdx @@ -9,6 +9,14 @@ Cline includes optional monitoring capabilities for organizations that want to t ## Monitoring Options + + Built-in anonymous usage tracking that helps improve Cline (opt-in) + + + + Backup conversation history to S3/R2 for compliance and analysis + + Export metrics and logs to your own observability backends @@ -18,12 +26,6 @@ Cline includes optional monitoring capabilities for organizations that want to t - - - Built-in anonymous usage tracking that helps improve Cline (opt-in) - - - ## Cline Telemetry Cline includes opt-in telemetry for anonymous usage tracking: diff --git a/docs/enterprise-solutions/monitoring/prompt-storage.mdx b/docs/enterprise-solutions/monitoring/prompt-storage.mdx new file mode 100644 index 0000000000..9780ae20dc --- /dev/null +++ b/docs/enterprise-solutions/monitoring/prompt-storage.mdx @@ -0,0 +1,666 @@ +--- +title: "Prompt Storage" +description: "Backup conversation history to S3 or Cloudflare R2 for compliance, audit, and analysis" +--- + +Prompt Storage allows enterprises to automatically back up Cline conversation history to cloud storage (AWS S3 or Cloudflare R2). This provides a centralized repository for compliance, audit trails, and usage analysis while maintaining local storage as the primary source of truth. + +## Overview + +Every Cline task conversation is stored locally in `~/.cline/data/tasks//api_conversation_history.json`. When prompt storage is enabled, a background sync worker automatically uploads these conversation files to your configured S3 or R2 bucket. + + + + Maintain conversation records for regulatory requirements and internal policies. + + + + Track AI interactions across your organization with timestamped conversation logs. + + + + Analyze conversation patterns, token usage, and model performance at scale. + + + + Backup conversation history independent of local storage for business continuity. + + + +## How It Works + +```mermaid +graph LR + A[User] --> B[Cline Extension] + B --> C[Local Storage
~/.cline/data/tasks/] + C --> D[Background Sync Worker] + D --> E[S3/R2 Bucket] + E --> F[Compliance/Analytics] +``` + +1. **Local Storage First**: All conversations are written to local disk immediately +2. **Background Sync**: A worker process queues conversation files for upload +3. **Reliable Upload**: Automatic retry logic with configurable batch sizes +4. **Cloud Backup**: Files are stored in your S3/R2 bucket with the same path structure + +## Storage Architecture + +### What Gets Stored + +Prompt storage uploads the following files from each task: + +| File | Content | Purpose | +|------|---------|---------| +| `api_conversation_history.json` | Full conversation in Anthropic MessageParam format | Core conversation data for analysis | +| Task metadata | Task ID, timestamps, model info | Correlation and indexing | + +### What's NOT Stored + +Prompt storage **does not** include: + +- ❌ Workspace files not accessed by Cline +- ❌ API keys or secrets +- ❌ User credentials or authentication tokens + + +Conversation history includes **all tool inputs and outputs**. This means code written via `write_to_file`, file contents read via `read_file`, and command outputs are included in the uploaded data. Review your compliance and data classification requirements before enabling. + + +### Storage Path Pattern + +Files are uploaded to your bucket following this structure: + +``` +s3://your-bucket/tasks/{taskId}/api_conversation_history.json +``` + +This mirrors the local storage structure, making it easy to correlate local and cloud data. + +## Configuration + +Prompt storage is configured through Remote Configuration in the `enterpriseTelemetry.promptUploading` section. + +### Schema + +```json +{ + "enterpriseTelemetry": { + "promptUploading": { + "enabled": true, + "type": "s3_access_keys", + "s3AccessSettings": { + "bucket": "your-cline-prompts", + "accessKeyId": "AKIAIOSFODNN7EXAMPLE", + "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY", + "region": "us-east-1", + "intervalMs": 30000, + "maxRetries": 5, + "batchSize": 10, + "maxQueueSize": 1000, + "maxFailedAgeMs": 604800000, + "backfillEnabled": false + } + } + } +} +``` + +### Configuration Fields + +#### Core Settings + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `enabled` | boolean | Yes | Enable/disable prompt storage | +| `type` | string | Yes | Storage type: `"s3_access_keys"` or `"r2_access_keys"` | + +#### Access Settings (S3/R2) + +| Field | Type | Required | Description | Default | +|-------|------|----------|-------------|---------| +| `bucket` | string | Yes | S3/R2 bucket name | - | +| `accessKeyId` | string | Yes | AWS/Cloudflare access key ID | - | +| `secretAccessKey` | string | Yes | AWS/Cloudflare secret access key | - | +| `region` | string | S3 only | AWS region (e.g., `us-east-1`) | - | +| `endpoint` | string | R2 only | Cloudflare R2 endpoint URL | - | +| `accountId` | string | R2 only | Cloudflare account ID | - | + +#### Sync Worker Settings + +| Field | Type | Description | Default | +|-------|------|-------------|---------| +| `intervalMs` | number | Milliseconds between sync attempts | 30000 (30s) | +| `maxRetries` | number | Maximum retries before giving up | 5 | +| `batchSize` | number | Items to process per interval | 10 | +| `maxQueueSize` | number | Maximum queue size before eviction | 1000 | +| `maxFailedAgeMs` | number | Time before discarding failed items | 604800000 (7 days) | +| `backfillEnabled` | boolean | Sync existing tasks on startup | false | + +## Setup Guides + + + + ### AWS S3 Configuration + + + + Create a dedicated S3 bucket for Cline conversation storage: + + ```bash + aws s3 mb s3://your-cline-prompts --region us-east-1 + ``` + + Enable versioning and encryption: + + ```bash + aws s3api put-bucket-versioning \ + --bucket your-cline-prompts \ + --versioning-configuration Status=Enabled + + aws s3api put-bucket-encryption \ + --bucket your-cline-prompts \ + --server-side-encryption-configuration '{ + "Rules": [{ + "ApplyServerSideEncryptionByDefault": { + "SSEAlgorithm": "AES256" + } + }] + }' + ``` + + + + Create an IAM policy with minimal required permissions: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:PutObjectAcl", + "s3:GetObject", + "s3:DeleteObject" + ], + "Resource": "arn:aws:s3:::your-cline-prompts/*" + }, + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket" + ], + "Resource": "arn:aws:s3:::your-cline-prompts" + } + ] + } + ``` + + Save this as `cline-prompt-storage-policy.json` and create the policy: + + ```bash + aws iam create-policy \ + --policy-name ClinePromptStorage \ + --policy-document file://cline-prompt-storage-policy.json + ``` + + + + Create a dedicated IAM user and attach the policy: + + ```bash + aws iam create-user --user-name cline-prompt-uploader + + aws iam attach-user-policy \ + --user-name cline-prompt-uploader \ + --policy-arn arn:aws:iam::YOUR_ACCOUNT_ID:policy/ClinePromptStorage + + aws iam create-access-key --user-name cline-prompt-uploader + ``` + + Save the `AccessKeyId` and `SecretAccessKey` from the output. + + + + In the Cline admin console at [app.cline.bot](https://app.cline.bot): + + 1. Navigate to **Settings** → **Enterprise Telemetry** + 2. Enable **Prompt Uploading** + 3. Select **S3** as the storage type + 4. Enter your bucket name, access key ID, secret key, and region + 5. Configure sync worker settings (or use defaults) + 6. Save configuration + + + + Use the "Test Connection" button in the admin console to verify: + - Bucket access + - Write permissions + - Credential validity + + A test file will be uploaded and deleted from your bucket. + + + + ### Optional: Lifecycle Policies + + Configure retention policies for cost management: + + ```json + { + "Rules": [ + { + "Id": "ArchiveOldPrompts", + "Status": "Enabled", + "Transitions": [ + { + "Days": 90, + "StorageClass": "GLACIER" + } + ] + }, + { + "Id": "DeleteOldPrompts", + "Status": "Enabled", + "Expiration": { + "Days": 2555 + } + } + ] + } + ``` + + + + ### Cloudflare R2 Configuration + + + + 1. Log in to the [Cloudflare Dashboard](https://dash.cloudflare.com) + 2. Navigate to **R2** in the sidebar + 3. Click **Create bucket** + 4. Name your bucket (e.g., `cline-prompts`) + 5. Select a location close to your users + 6. Click **Create bucket** + + + + 1. In the R2 dashboard, click **Manage R2 API Tokens** + 2. Click **Create API token** + 3. Configure permissions: + - **Token name**: Cline Prompt Storage + - **Permissions**: Object Read & Write + - **Bucket**: Select your bucket or use All buckets + 4. Click **Create API Token** + 5. Save the **Access Key ID** and **Secret Access Key** + 6. Note your **Account ID** (shown in the R2 overview) + + + + Your R2 endpoint follows this format: + + ``` + https://.r2.cloudflarestorage.com + ``` + + Find your account ID in the Cloudflare dashboard under R2 overview. + + + + In the Cline admin console at [app.cline.bot](https://app.cline.bot): + + 1. Navigate to **Settings** → **Enterprise Telemetry** + 2. Enable **Prompt Uploading** + 3. Select **R2** as the storage type + 4. Enter: + - Bucket name + - Access key ID + - Secret access key + - Account ID + - Endpoint URL + 5. Configure sync worker settings (or use defaults) + 6. Save configuration + + + + Use the "Test Connection" button to verify: + - Bucket access with provided credentials + - Write permissions + - Endpoint connectivity + + + + ### Cost Advantages + + R2 offers significant cost advantages over S3: + - **No egress fees**: Download data at no cost + - **Lower storage costs**: ~$0.015/GB vs S3's ~$0.023/GB + - **Global edge access**: Fast access from anywhere + + + +## Sync Worker Behavior + +The background sync worker manages the upload queue with these characteristics: + +### Queue Management + +- **FIFO ordering**: Files are uploaded in the order they were created +- **Automatic batching**: Processes up to `batchSize` items per interval +- **Queue size limits**: Evicts oldest items when `maxQueueSize` is exceeded +- **Retry logic**: Failed uploads are retried up to `maxRetries` times + +### Failure Handling + +When an upload fails: + +1. **Immediate retry**: Item stays in queue for next sync interval +2. **Exponential backoff**: Retry attempts are spaced out +3. **Maximum retries**: After `maxRetries` attempts, item is marked as permanently failed +4. **Age-based cleanup**: Failed items older than `maxFailedAgeMs` are discarded +5. **No data loss**: Local files remain intact regardless of sync status + +### Backfill Mode + +When `backfillEnabled` is set to `true`: + +- On first startup, scans all existing tasks in `~/.cline/data/tasks/` +- Queues conversation files that haven't been uploaded +- Useful for enabling prompt storage on an existing Cline deployment +- Can generate significant upload volume — monitor queue size + + +Enable backfill carefully on large deployments. Consider starting with `backfillEnabled: false` and monitoring the steady-state queue before enabling backfill. + + +## Monitoring & Observability + +### Integration with OpenTelemetry + +While prompt storage operates independently, it integrates with Cline's observability system: + +- **Task lifecycle events**: `task.created`, `task.completed` track when conversations are generated +- **Conversation events**: `task.conversation_turn`, `task.tokens` provide usage metrics +- **Local monitoring**: Sync worker status is logged but not yet exported as OTel events + +See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for configuring metrics export. + +### CloudWatch Monitoring (S3) + +Monitor S3 upload activity with CloudWatch: + +```bash +# View PutObject requests (uploads) +aws cloudwatch get-metric-statistics \ + --namespace AWS/S3 \ + --metric-name NumberOfObjects \ + --dimensions Name=BucketName,Value=your-cline-prompts \ + --start-time 2026-03-01T00:00:00Z \ + --end-time 2026-03-08T00:00:00Z \ + --period 3600 \ + --statistics Sum +``` + +### R2 Analytics + +Cloudflare R2 provides built-in analytics in the dashboard: + +- Request counts and rates +- Storage usage over time +- Bandwidth utilization +- Error rates + +## Security & Compliance + +### Encryption + +**At Rest:** +- S3: Enable server-side encryption (SSE-S3 or SSE-KMS) +- R2: Encryption enabled by default + +**In Transit:** +- All uploads use HTTPS/TLS +- Credentials are never logged or exposed + +### Access Control + +**Recommended IAM policies:** + +- Use dedicated IAM users/roles +- Limit permissions to write-only if read access isn't needed +- Enable MFA for credential generation +- Rotate access keys regularly + +**Bucket policies:** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Deny", + "Principal": "*", + "Action": "s3:*", + "Resource": [ + "arn:aws:s3:::your-cline-prompts/*", + "arn:aws:s3:::your-cline-prompts" + ], + "Condition": { + "Bool": { + "aws:SecureTransport": "false" + } + } + } + ] +} +``` + +### Audit Logging + +**S3 Server Access Logging:** + +```bash +aws s3api put-bucket-logging \ + --bucket your-cline-prompts \ + --bucket-logging-status '{ + "LoggingEnabled": { + "TargetBucket": "your-log-bucket", + "TargetPrefix": "cline-prompts-access/" + } + }' +``` + +**CloudTrail for API Calls:** + +Enable CloudTrail to track all S3 API operations on your bucket. + +### Data Retention + +Implement retention policies based on your compliance requirements: + +- **GDPR**: Consider right to erasure +- **SOC 2**: Maintain audit trails for required period +- **HIPAA**: Ensure appropriate retention and disposal + +## Troubleshooting + +### Common Issues + + + + **Symptoms**: `maxQueueSize` limit reached, oldest items being evicted + + **Causes**: + - Upload rate slower than conversation creation rate + - Network connectivity issues + - Insufficient batch size or interval + + **Solutions**: + 1. Increase `batchSize` to process more items per interval + 2. Decrease `intervalMs` to sync more frequently + 3. Check network connectivity and credentials + 4. Temporarily increase `maxQueueSize` while investigating + + + + **Symptoms**: Repeated upload failures, items reaching `maxRetries` + + **Causes**: + - Invalid or expired credentials + - Insufficient IAM permissions + - Bucket policy denying access + + **Solutions**: + 1. Verify credentials are correct in remote config + 2. Check IAM policy includes `s3:PutObject` permission + 3. Review bucket policies for deny rules + 4. Test with AWS CLI: `aws s3 cp test.txt s3://your-bucket/` + + + + **Symptoms**: Connection timeouts, failed uploads + + **Causes**: + - Incorrect endpoint URL + - Firewall blocking Cloudflare IPs + - Invalid account ID + + **Solutions**: + 1. Verify endpoint format: `https://.r2.cloudflarestorage.com` + 2. Check firewall rules allow HTTPS to Cloudflare IPs + 3. Confirm account ID in Cloudflare dashboard + 4. Test with curl: `curl -I https://.r2.cloudflarestorage.com` + + + + **Symptoms**: Queue at max size immediately after enabling backfill + + **Causes**: + - Large number of existing tasks + - Backfill queuing faster than upload processing + + **Solutions**: + 1. Disable backfill temporarily: `"backfillEnabled": false` + 2. Let steady-state queue drain first + 3. Increase `batchSize` and decrease `intervalMs` + 4. Consider `maxQueueSize` increase during backfill period + 5. Re-enable backfill once queue is stable + + + +### Debug Logging + +Enable debug logging to diagnose sync issues: + +1. Check extension developer console (Help → Toggle Developer Tools) +2. Look for `[ClineBlobStorage]` and `[SyncWorker]` log entries +3. Failed uploads log error messages with details + +### Testing Configuration + +Use the built-in test connection feature: + +```typescript +// Programmatic test (for custom integrations) +import { testPromptUploading } from '@/core/controller/state/testPromptUploading' + +await testPromptUploading(controller) +// Returns: { success: boolean, message: string } +``` + +## Data Format Reference + +### Conversation File Schema + +Uploaded `api_conversation_history.json` files contain an array of messages: + +```json +[ + { + "role": "user", + "content": [ + { + "type": "text", + "text": "Create a React component for a todo list" + } + ] + }, + { + "role": "assistant", + "content": [ + { + "type": "text", + "text": "I'll create a todo list component..." + }, + { + "type": "tool_use", + "id": "toolu_123", + "name": "write_to_file", + "input": { + "path": "TodoList.tsx", + "content": "..." + } + } + ] + } +] +``` + +This follows the [Anthropic Messages API format](https://docs.anthropic.com/claude/reference/messages_post). + +### Metadata Schema + +Task metadata includes: + +```json +{ + "taskId": "1234567890", + "createdAt": "2026-03-05T10:30:00Z", + "lastModified": "2026-03-05T11:45:00Z", + "modelInfo": { + "id": "claude-sonnet-4", + "provider": "anthropic" + }, + "tokensUsed": { + "input": 1250, + "output": 3400 + } +} +``` + +## Best Practices + + + + Test with a single team or project before rolling out organization-wide. + + + + Set up billing alerts and review storage usage monthly. + + + + Use dedicated IAM users with minimal permissions and rotate keys regularly. + + + + Define and implement data retention policies based on compliance needs. + + + +## See Also + + + + Configure metrics and logs export for comprehensive observability + + + + Learn about Cline's built-in anonymous usage tracking + + + + Understand the remote configuration system + + diff --git a/docs/enterprise-solutions/monitoring/telemetry.mdx b/docs/enterprise-solutions/monitoring/telemetry.mdx index a4a8808529..cfb2a6ab45 100644 --- a/docs/enterprise-solutions/monitoring/telemetry.mdx +++ b/docs/enterprise-solutions/monitoring/telemetry.mdx @@ -83,11 +83,22 @@ Administrators can set default telemetry state through remote configuration: Even with enterprise configuration, individual users can still disable Cline Telemetry in their local settings. -## Advanced Monitoring +## Enterprise Monitoring Features -For organizations needing detailed monitoring, Cline supports optional OpenTelemetry integration to export telemetry data to your own observability systems. +For organizations with additional compliance or monitoring requirements, Cline provides: -See [Enterprise Monitoring](/enterprise-solutions/monitoring/overview) for details on available monitoring options. +### Prompt Storage +Automatically backup conversation history to AWS S3 or Cloudflare R2 for: +- Compliance and audit trails +- Usage analysis and reporting +- Disaster recovery + +See [Prompt Storage](/enterprise-solutions/monitoring/prompt-storage) for configuration details. + +### OpenTelemetry Integration +Export detailed metrics and logs to your own observability platforms like Datadog, New Relic, or Grafana Cloud. + +See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for setup instructions. ## Privacy @@ -127,7 +138,7 @@ Anonymous usage data helps: Enterprise monitoring and observability - - Full telemetry documentation + + See what data is collected