Back to Cline

OpenTelemetry Events Reference

docs/enterprise-solutions/monitoring/opentelemetry-events.mdx

3.82.019.8 KB
Original Source

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.

<Info> Events are only emitted when OpenTelemetry is enabled. See [OpenTelemetry](/enterprise-solutions/monitoring/opentelemetry) for configuration instructions. </Info>

Event Categories

Cline emits events across several categories, each prefixed with a namespace:

<CardGroup cols={3}> <Card title="user.*" icon="user"> Authentication, telemetry controls, extension lifecycle </Card> <Card title="task.*" icon="list-check"> Task execution, conversation turns, tool usage, tokens </Card> <Card title="workspace.*" icon="folder-tree"> Workspace initialization, VCS detection, path resolution </Card> <Card title="ui.*" icon="window"> User interface interactions and model selection </Card> <Card title="hooks.*" icon="webhook"> Hook discovery, execution, and context modification </Card> <Card title="worktree.*" icon="code-branch"> Git worktree operations and merge handling </Card> <Card title="host.*" icon="computer"> Host environment detection </Card> <Card title="test.*" icon="flask"> Diagnostic and connection testing </Card> </CardGroup>

User Events

Events related to user authentication, telemetry preferences, and extension lifecycle.

EventDescriptionKey Attributes
user.opt_outUser explicitly opts out of telemetryuser_id, timestamp
user.opt_inUser explicitly opts into telemetryuser_id, timestamp
user.telemetry_enabledTelemetry service enabled/initialization signalenabled, timestamp
user.extension_activatedExtension activation eventextension_version, host_type
user.extension_storage_errorError while reading/writing extension storage stateerror_type, error_message
user.auth_startedAuthentication flow startedprovider, timestamp
user.auth_succeededAuthentication flow succeededprovider, user_id
user.auth_failedAuthentication flow failedprovider, error_reason
user.auth_logged_outUser logged outreason, provider
user.onboarding_progressOnboarding step/action progressstep, 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.

EventDescriptionKey Attributes
workspace.initializedWorkspace initialization completedroots_count, vcs_type, duration_ms
workspace.init_errorWorkspace initialization failederror_type, fallback_used
workspace.vcs_detectedVersion control system detection eventvcs_type, root_path_hash
workspace.multi_root_checkpointMulti-root checkpoint operation telemetryoperation, roots_count, duration_ms
workspace.path_resolvedWorkspace path resolutionhint, 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

EventDescriptionKey Attributes
task.createdNew task/conversation startedtask_id, mode, model, provider
task.restartedExisting task restarted/reopenedtask_id, time_since_last_message
task.completedTask completedtask_id, duration_ms, model, provider, tokens_total
task.feedbackUser feedback on tasktask_id, feedback_type (thumbs_up/thumbs_down)
task.historical_loadedHistorical task loaded from storagetask_id, age_days
task.retry_clickedUser clicked retry on a failed action/requesttask_id, action_type

Conversation & Tokens

EventDescriptionKey Attributes
task.conversation_turnConversation turn eventrole (user/assistant), provider, model, tokens_in, tokens_out
task.tokensToken usage eventtokens_in, tokens_out, cached_tokens, cost
task.modePlan/Act mode switch eventprevious_mode, new_mode, task_id

Tool Usage

EventDescriptionKey Attributes
task.tool_usedTool invocation and outcome telemetrytool_name, success, duration_ms, auto_approved
task.mcp_tool_calledMCP tool call lifecycle eventstatus (started/success/error), tool_name, server_name
task.browser_tool_startBrowser tool/session startedurl, action
task.browser_tool_endBrowser tool/session ended with statsduration_ms, actions_count, success
task.browser_errorBrowser tool error eventerror_type, url
task.terminal_executionTerminal execution capture success/failure eventsuccess, command_hash, duration_ms
task.terminal_output_failureTerminal output capture failedreason
task.terminal_user_interventionUser intervention during terminal executionintervention_type
task.terminal_hangTerminal hang/stuck detection eventduration_ms, command_hash

Features & Options

EventDescriptionKey Attributes
task.checkpoint_usedCheckpoint action usedaction (create/restore/compare), task_id
task.option_selectedUser selected one of AI-provided optionsoption_index, total_options
task.options_ignoredUser ignored AI options and entered custom inputoptions_count
task.slash_command_usedSlash command/workflow/MCP prompt command usedcommand_name, is_workflow
task.mention_usedMention resolution succeededmention_type (file/url/folder/terminal/problems/git)
task.mention_failedMention resolution failedmention_type, error_reason
task.mention_search_resultsMention search query result telemetryquery, results_count
task.workspace_search_patternWorkspace search strategy/pattern telemetrypattern_type, files_scanned

Advanced Features

EventDescriptionKey Attributes
task.focus_chain_enabledFocus chain feature enabledtask_id
task.focus_chain_disabledFocus chain feature disabledtask_id
task.focus_chain_progress_firstFirst focus-chain checklist/progress emitteditems_count
task.focus_chain_progress_updateSubsequent focus-chain checklist/progress updatesitems_total, items_completed
task.focus_chain_incomplete_on_completionTask completed while focus-chain checklist still incompleteitems_remaining
task.focus_chain_list_openedFocus-chain markdown/list opened by usertask_id
task.focus_chain_list_writtenFocus-chain markdown/list written/savedtask_id
task.subagent_enabledSubagents feature enabledtask_id
task.subagent_disabledSubagents feature disabledtask_id
task.subagent_startedSubagent execution startedsubagent_id, prompt_length
task.subagent_completedSubagent execution completedsubagent_id, duration_ms, success
task.skill_usedSkill invocation eventskill_name, task_id

Auto-Compact & Context

EventDescriptionKey Attributes
task.summarize_taskAuto-compaction/summarize triggered for context pressureconversation_length, estimated_tokens
task.auto_condense_toggledAuto-condense setting toggledenabled

Settings & Features

EventDescriptionKey Attributes
task.feature_toggledGeneric feature toggle changedfeature_name, enabled
task.rule_toggledCline rule toggled on/offrule_name, enabled, is_global
task.yolo_mode_toggledYOLO mode toggledenabled
task.cline_web_tools_toggledCline web tools setting toggledenabled

API & Performance

EventDescriptionKey Attributes
task.gemini_api_performanceGemini-specific API performance telemetryduration_ms, tokens, cache_hit
task.provider_api_errorAPI provider error eventprovider, model, error_code, error_message
task.diff_edit_failedDiff/replace edit failedfile_path_hash, error_type
task.initializationTask initialization timing/metadata eventduration_ms, mode

AI Output Feedback

EventDescriptionKey Attributes
task.ai_output.acceptedAI-generated file edit acceptedlines_added, lines_removed, file_count
task.ai_output.rejectedAI-generated file edit rejectedlines_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.

EventDescriptionKey Attributes
ui.model_selectedModel selected in UImodel, provider, previous_model
ui.model_favorite_toggledModel favorite toggledmodel_id, is_favorited
ui.button_clickedUI button click eventbutton_id, context
ui.rules_menu_openedRules/workflows menu/modal openedmenu_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.

EventDescriptionKey Attributes
hooks.enabledHooks feature enableduser_id
hooks.disabledHooks feature disableduser_id
hooks.cancel_requestedHook requested cancellationhook_name, task_id
hooks.context_modifiedHook modified contexthook_name, modification_type
hooks.discovery_completedHook discovery completedhooks_count, global_count, workspace_count
hooks.executionUnified hook execution lifecyclehook_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.

EventDescriptionKey Attributes
worktree.view_openedWorktree view openeduser_id
worktree.createdWorktree create eventsuccess, branch_name, duration_ms
worktree.merge_attemptedWorktree merge attempt eventhas_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.

EventDescriptionKey Attributes
host.detectedHost environment detection eventhost_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.

EventDescriptionKey Attributes
cline.test.connectionOTEL connection test event from "Test OTEL Connection" flowsuccess, 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:

AttributeTypeDescription
timestampISO 8601Event occurrence time
user_idstringAnonymized user identifier (when authenticated)
session_idstringCurrent session identifier
extension_versionstringCline extension version
host_typestringvscode, 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
<Warning> File paths, command arguments, and code content are **never** included in raw form. Only hashes or anonymized identifiers are used. </Warning>

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

<Warning> **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. </Warning>

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

<Note> 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. </Note>

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

<CardGroup cols={2}> <Card title="Filter Noise" icon="filter"> Focus on events relevant to your use case. Not all events need dashboards. </Card> <Card title="Set Alerts" icon="bell"> Alert on error events and usage anomalies for proactive monitoring. </Card> <Card title="Aggregate Metrics" icon="chart-bar"> Roll up events into metrics for long-term trend analysis. </Card> <Card title="Respect Privacy" icon="shield"> Remember events are already anonymized. Don't attempt to de-anonymize. </Card> </CardGroup>

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

<CardGroup cols={3}> <Card title="OpenTelemetry Setup" icon="chart-line" href="/enterprise-solutions/monitoring/opentelemetry"> Configure OTel integration </Card> <Card title="Prompt Storage" icon="database" href="/enterprise-solutions/monitoring/prompt-storage"> Backup conversation history </Card> <Card title="Telemetry" icon="chart-simple" href="/enterprise-solutions/monitoring/telemetry"> Basic telemetry overview </Card> </CardGroup>