VS Code extension analytics

Overview

The Cloudinary VS Code extension reports usage data through three separate mechanisms:

• UI events. The extension explicitly reports named events, such as library_opened or upload_succeeded, to the Cloudinary analytics endpoint. These events describe what a developer did inside the editor.
• API call attribution. Every Admin API and Upload API call the extension makes carries a CloudinaryVSCode/<version> user agent, so extension traffic is identifiable in the standard API logs without any separate reporting.
• Delivery URL analytics. Delivery URLs the extension generates carry an _a parameter that identifies the Node SDK rather than the extension, so it can't be used for extension attribution. See Delivery URL analytics.

The first two land in the same Snowflake data source, CLOUDINARY.LOGS.UDR_RAW, because the analytics endpoint is itself a Cloudinary API controller. The third rides on delivery URLs and is recorded in the CDN delivery logs.

How UI events are reported

UI events are sent by AnalyticsService in src/analytics/analyticsService.ts. A single instance is created during activation in src/extension.ts and passed to every command and webview provider that needs it.

Each event is one HTTP POST request, with the whole payload in the query string:

Requests are fire and forget. track() doesn't await the response, and any network failure is swallowed, so analytics can never block or break an extension workflow.

Parameters sent with every event

The analytics service attaches these parameters to every event, regardless of the event name.

Payload rules

The analytics service normalizes and filters every event payload before sending it:

• Event names must match ^[a-z][a-z0-9_]*$. An event with any other name is silently dropped, so it never reaches the endpoint.
• Keys keep the spelling supplied by the caller. Reserved and sensitive key checks are case-insensitive and treat hyphens, dots, and whitespace as underscores.
• Values are converted to strings. Only strings, finite numbers, and true or false values survive. Empty strings, null, undefined, NaN, Infinity, objects, and arrays are dropped.
• Reserved keys are dropped so an event payload can't overwrite a common parameter: source, extension_version, ide_platform, session_id, event_time, and event.
• Sensitive keys are dropped. Blocked names include credentials and tokens (api_key, api_secret, access_token, authorization, client_secret, password, refresh_token, secret, token, id_token), contact details (email, user_email, phone), and message content (prompt, message, message_content, user_message). Equivalent camel case and punctuation variants are also blocked.

Current analytics events don't include search text, Docs AI prompts, feedback comments, public IDs, URLs, or file paths. asset_search and message_sent report character counts instead. Docs AI sends conversation content to the Docs AI API as part of chat and feedback workflows; that traffic is separate from analytics reporting.

cloud_name and debug_id aren't reserved. An event-specific payload with either name replaces the corresponding common value.

Events reported from the Docs AI webview

The Docs AI view runs in a webview, which has no direct access to the analytics service. Its client code calls a local trackAnalytics() helper that posts an analyticsEvent message to the extension host, and DocsAiViewProvider._handleAnalyticsEvent forwards the name and payload to AnalyticsService.track().

The forwarding path doesn't use an allowlist of event names. The event name regex in the analytics service is the only guard, so any renamed event in the webview client reaches the endpoint under its new name without a matching change on the extension host side.

UI event catalog

Lifecycle and configuration

Navigation

Library

Upload

Clipboard

Docs AI

These events originate in the webview client, src/webview/client/docs-ai/, and are relayed through the extension host.

Attributing API calls to the extension

The extension doesn't report a separate analytics event for each Cloudinary API call. Instead, it identifies itself on the calls themselves, so API traffic is attributable using the standard API logs.

generateUserAgent() in src/utils/userAgent.ts builds the identifier:

For example, CloudinaryVSCode/1.0.1 (Cursor 1.99.3). The editor name is normalized to VSCode, Cursor, Windsurf, VSCodeInsiders, or VSCodeOSS, with a camel case fallback for anything unrecognized.

This identifier is applied in two places:

• SDK calls. Activation and environment switching set cloudinary.utils.userPlatform. The Node SDK adds that value in front of its own user agent, so the header becomes CloudinaryVSCode/1.0.1 (Cursor 1.99.3) CloudinaryNodeJS/<sdk version> (Node <node version>).
• Direct calls. The folder mode check in src/config/detectFolderMode.ts calls fetch directly and sets the User-Agent header itself.

In Snowflake, the header is available as HTTP_REQUEST_HEADERS:user_agent. The key uses an underscore, not the hyphen used on the wire.

The endpoints the extension currently calls are FoldersApiController/show, FoldersApiController/index, ResourceSearchApiController/index, ResourcesApiController/customer_configuration, UploadPresetsApiController/index, and UploadController/upload.

Delivery URL analytics

Delivery URLs the extension builds with cloudinary.url() carry an _a query parameter that the Node SDK appends automatically. The SDK's urlAnalytics option defaults to true and the extension doesn't disable it, so the optimized URLs and signed original URLs shown in the library and preview panels all include it.

_a encodes the SDK identity only: the SDK code, the SDK version, the language runtime version, and the product. It doesn't carry the extension version or the userPlatform string, so it can't be used to attribute delivery traffic to the VS Code extension. Extension attribution relies on the user agent described above.

Two consequences worth knowing:

• A URL a developer copies out of the extension keeps its _a value, so once that URL is pasted into application code the delivery traffic is reported against the Node SDK rather than the extension.
• Requests for these URLs are delivery traffic and are recorded in the CDN delivery logs, not in the API records that the rest of this page queries.

Where the data lands in Snowflake

The analytics endpoint is a Cloudinary API controller, so UI events flow through the standard usage data record (UDR) pipeline rather than a dedicated events table.

UI events in UDR_RAW are identified by HTTP_QUERY_PARAMS:source = 'vscode_extension'. They resolve to ENDPOINT = 'AnalyticsController/collect', SERVICE_NAME = 'core', and, in the aggregate table, FEATURE = 'vscode_extension' with SOURCE = 'analytics'.

Known data quality caveats

• Version 0.1.6 double reports. Version 0.1.6 sent a GET request with no event parameter alongside its POST. Filter on HTTP_REQUEST_METHOD = 'POST', or on HTTP_QUERY_PARAMS:event IS NOT NULL, or those rows inflate volume without being attributable to any event. Versions 1.0.0 and later send only the POST.
• Test traffic. Events reported during development carry extension_version = 'local_test', or a debug_id parameter. Exclude both from adoption figures.
• endpoint_check isn't a product event. It appears in historical data from the endpoint's initial verification and isn't reported by any current code path.
• Client clocks. event_time comes from the developer's machine and can be wrong. UDR_RAW.TIMESTAMP is the server clock and is the safer choice for time bucketing.
• Sessions aren't users. session_id is created once per installation and persists in global state, so it approximates an installation rather than either a user or an editor session. Cloudinary user IDs aren't reported with UI events, because the extension authenticates with API key and secret rather than as a Console user.
• Asset previews can report twice. Opening an asset from Library or an upload result first reports asset_opened with its source entry point, then reports the same event with entry_point = 'preview_command' when the shared preview command runs.
• Library folder uploads report twice. Opening the upload panel from the Library folder tree reports upload_widget_opened with entry_point = 'library_context', then reports it again with entry_point = 'folder_context' when the upload command runs.

Sample queries

These queries run against Snowflake directly and work unchanged in Redash.

Daily event volume by event name. The starting point for most questions:

Adoption by editor and version. Distinct installations and product environments per week:

View events by entry point. The command value covers both Command Palette actions and in-editor actions that invoke the same command. The webview_ready value identifies webview initialization:

Upload outcomes. Success rate split by upload source:

Configuration failure reasons. Useful when investigating setup friction:

API calls made by the extension. Attributed by user agent rather than by a reported event:

Long-range request volume from the aggregate. Cheaper than UDR_RAW, but with no event breakdown:

Adding a new event

1. Pick a name that matches ^[a-z][a-z0-9_]*$ and follows the existing object_verb pattern, for example asset_opened, not openAsset.
2. Report it through the shared analytics service. In commands and providers, call analytics?.track(). In the Docs AI webview, call the local trackAnalytics() helper.
3. Keep the payload low cardinality and free of content. Report lengths, counts, flags, and enumerated values. Never report public IDs, URLs, file paths, search text, or prompts.
4. Reuse existing parameter names. entry_point, resource_type, asset_type, and copy_type already have established value sets, and reusing them keeps queries simple.
5. Add the event to the UI event catalog in the same pull request.
6. Verify the event end to end by setting CLOUDINARY_ANALYTICS_DEBUG_ID to a unique value before launching the extension, then querying LOGS.UDR_RAW for that debug_id.

Resources

• Cloudinary VS Code Extension for development and publishing
• Analytics service for the reporting implementation
• Configuration validation tracking for the configuration validation events
• User agent utility for the API call identifier