{"id":28420646,"url":"https://github.com/redhat-developer/vscode-redhat-telemetry","last_synced_at":"2025-06-26T17:31:55.777Z","repository":{"id":40281852,"uuid":"331893140","full_name":"redhat-developer/vscode-redhat-telemetry","owner":"redhat-developer","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-12T19:34:02.000Z","size":4047,"stargazers_count":28,"open_issues_count":14,"forks_count":29,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-06-05T05:29:16.163Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-developer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-22T09:09:05.000Z","updated_at":"2025-05-15T07:53:17.000Z","dependencies_parsed_at":"2024-06-13T16:27:13.532Z","dependency_job_id":null,"html_url":"https://github.com/redhat-developer/vscode-redhat-telemetry","commit_stats":{"total_commits":112,"total_committers":7,"mean_commits":16.0,"dds":0.4375,"last_synced_commit":"9655bbe2731cf7d4bfb27283dd7b7ff658bd0e74"},"previous_names":[],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/redhat-developer/vscode-redhat-telemetry","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Fvscode-redhat-telemetry","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Fvscode-redhat-telemetry/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Fvscode-redhat-telemetry/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Fvscode-redhat-telemetry/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-developer","download_url":"https://codeload.github.com/redhat-developer/vscode-redhat-telemetry/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Fvscode-redhat-telemetry/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262113320,"owners_count":23261005,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-05T03:48:59.519Z","updated_at":"2025-06-26T17:31:55.725Z","avatar_url":"https://github.com/redhat-developer.png","language":"TypeScript","readme":"[![npm](https://img.shields.io/npm/v/@redhat-developer/vscode-redhat-telemetry?color=brightgreen)](https://www.npmjs.com/package/@redhat-developer/vscode-redhat-telemetry)\n\n# Red Hat Telemetry Collection API\n\nThis library provides a telemetry collection API for extensions published by Red Hat. **After getting the user's approval, anonymous** [usage data](https://github.com/redhat-developer/vscode-redhat-telemetry/blob/HEAD/USAGE_DATA.md) is collected and sent to Red Hat servers, to help improve our products and services. Read our [privacy statement](https://developers.redhat.com/article/tool-data-collection) to learn more about it.\n\nThe first time one of Red Hat's extensions engaging in telemetry collection runs, the user will be asked to opt-in Red Hat's telemetry collection program:\n\n![Opt-in request](images/optin-popup.png)\n\nWhether the request is accepted or denied, this pop up will not show again.\n\nIt's also possible to opt-in later, by setting the `redhat.telemetry.enabled` user setting to `true`.\n\nFrom File \u003e Preferences \u003e Settings (On macOS: Code \u003e Preferences \u003e Settings), search for telemetry, and check the `Redhat \u003e Telemetry : Enabled` setting. This will enable sending all telemetry events from Red Hat extensions going forward.\n\n\n## How to disable telemetry reporting?\nIf you want to stop sending usage data to Red Hat, you can set the `redhat.telemetry.enabled` user setting to `false`. \n\nFrom File \u003e Preferences \u003e Settings (On macOS: Code \u003e Preferences \u003e Settings), search for telemetry, and uncheck the `Redhat \u003e Telemetry : Enabled` setting. This will silence all telemetry events from Red Hat extensions going forward.\n\nAdditionally, and starting from version 0.5.0, this module abides by Visual Studio Code's telemetry level: if `telemetry.telemetryLevel` is set to `off`, then no telemetry events will be sent to Red Hat, even if `redhat.telemetry.enabled` is set to `true`. If `telemetry.telemetryLevel` is set to `error` or `crash`, only events containing an `error` or `errors` property will be sent to Red Hat.\n\n# Remote configuration\nStarting from version 0.5.0, Red Hat Telemetry can be remotely configured. Once every 12h (or whatever is remotely configured), [telemetry-config.json](src/config/telemetry-config.json) will be downloaded to, depending on your platform:\n\n- **Windows** `%APPDATA%\\Code\\User\\globalStorage\\vscode-redhat-telemetry\\cache\\telemetry-config.json`\n- **macOS** `$HOME/Library/Application\\ Support/Code/User/globalStorage/vscode-redhat-telemetry/cache/telemetry-config.json`\n- **Linux** `$HOME/.config/Code/User/globalStorage/vscode-redhat-telemetry/cache/telemetry-config.json`\n\nThis allows Red Hat extensions to limit the events to be sent, by including or excluding certain events, by name or containing properties, or by limiting the ratio of users sending data.\neg.:\n- 50% of `redhat.vscode-hypothetical` users only, to report error events, excluding stackoverflows:\n\nStarting with 0.6.1, you can configure ratios on included events, meaning X% of the users will send a particular event (does not mean X% of the events will be sent!).\n\n```json\n{\n    \"*\": {\n        \"enabled\":\"all\", // supports \"all\", \"error\", \"crash\", \"off\"\n        \"refresh\": \"12h\",\n        \"includes\": [\n            {\n                \"name\" : \"startup\",\n                \"dailyLimit\": \"1\" // Limit to 1 event per day per extension\n            },\n            {\n                \"name\" : \"*\" // Always put wildcard patterns last in the array, to ensure other events are included\n            }\n        ]\n    },\n    \"redhat.vscode-hypothetical\": {\n        \"enabled\": \"error\", \n        \"ratio\": \"0.5\", // 50% of the users will send data\n        \"excludes\": [\n            {\n                \"property\": \"error\",\n                \"value\": \"*stackoverflow*\"\n            }\n        ]\n    },\n    \"redhat.vscode-mythological\": {\n        \"enabled\": \"all\", \n        \"includes\": [\n            {\n                \"name\": \"something-too-frequent\",\n                \"ratio\":\"0.1\" // 10% of the users will send that event\n            },\n            {\n                \"name\": \"something-less-frequent\",// all users could send that event but ...\n            }\n        ],\n        \"excludes\": [\n            {\n                \"name\": \"something-less-frequent\",\n                \"ratio\":\"0.997\" //... actually 99.7% of the users won't send that event\n            }\n        ]\n    }\n}\n```\n\nExtension configuration inherits and overrides the `*` configuration.\n\n\n# How to use this library\n\n## Add the `@redhat-developer/vscode-redhat-telemetry` dependency\n\nIn order to install [`@redhat-developer/vscode-redhat-telemetry`](https://github.com/redhat-developer/vscode-redhat-telemetry/) in your VS Code extension, open a terminal and execute:\n\n```\nnpm i @redhat-developer/vscode-redhat-telemetry\n```\n## Contribute the `redhat.telemetry.enabled` preference\nUnless your extension already depends on a telemetry-enabled Red Hat extension, it needs to declare the `redhat.telemetry.enabled` preference in its package.json, like:\n\n```\n\"contributes\": {\n    \"configuration\": {\n      ...\n      \"properties\": {\n        ...\n        \"redhat.telemetry.enabled\": {\n          \"type\": \"boolean\",\n          \"default\": null,\n          \"markdownDescription\": \"Enable usage data and errors to be sent to Red Hat servers. Read our [privacy statement](https://developers.redhat.com/article/tool-data-collection).\",\n          \"tags\":[ \"telemetry\", \"usesOnlineServices\" ],\n          \"scope\": \"window\"\n        },\n      }\n    }\n}\n```\n## [Optional] Add a custom segment key in package.json file\nBy default, extensions will send their data to https://app.segment.com/redhat-devtools/sources/vscode/. In development mode, the data is sent to https://app.segment.com/redhat-devtools/sources/vs_code_tests/.\n\n- You can specify custom segment keys in your package.json, to connect and push usage data to https://segment.com/\n\n```json\n    \"segmentWriteKey\": \"your-segment-key-goes-here\",\n    \"segmentWriteKeyDebug\": \"your-segment-key-goes-here-for-dev-mode\",\n```\n\n## Add the below code to your `extension.ts`\n\nGet a reference to the RedHatService instance from your VS Code extension's `activate` method in `extension.ts`:\n```typescript\nimport { getRedHatService, TelemetryService } from \"@redhat-developer/vscode-redhat-telemetry\";\n\nlet telemetryService: TelemetryService = null;\n\nexport async function activate(context: ExtensionContext) {\n  const redhatService = await getRedHatService(context);  \n  telemetryService = await redhatService.getTelemetryService();\n  telemetryService.sendStartupEvent();\n  ...\n}\n```\n\nSend events from the telemetryService reference:\n\n```typescript\n...\nif (telemetryService) {\n  telemetryService.send({name: \"Simplest event\"});\n  ...\n  let event = {\n    name: \"Test Event\",\n    type: \"track\", // optional type (track is the default)\n    properties: { // optional custom properties\n      foo: \"bar\", \n    }\n  };\n  telemetryService.send(event);\n}\n```\n\nTo access the anonymous Red Hat UUID for the current user:\n```typescript\nconst redhatUuid = await (await redhatService.getIdProvider()).getRedHatUUID();\n```\n\nOnce your extension is deactivated, a shutdown event, including the session duration, will automatically be sent on its behalf. However, shutdown event delivery is not guaranteed, in case VS Code is faster to exit than to send those last events.\n\nAll event properties are automatically sanitized to anonymize all paths (best effort) and references to the username.\n\n\n## Publicly document your data collection\n\nOnce telemetry is in place, you need to document the extent of the telemetry collection performed by your extension.\n* add a USAGE_DATA.md page to your extension's repository, listing the type of data being collected by your extension.\n* add a `Data and Telemetry` paragraph at the end of your extension's README file:\n\u003e `The ***** extension collects anonymous [usage data](USAGE_DATA.md) and sends it to Red Hat servers to help improve our products and services. Read our [privacy statement](https://developers.redhat.com/article/tool-data-collection) to learn more. This extension respects the `redhat.telemetry.enabled` setting which you can learn more about at https://github.com/redhat-developer/vscode-redhat-telemetry#how-to-disable-telemetry-reporting`\n\n* add a reference to your telemetry documentation page to this repository's own [USAGE_DATA.md](https://github.com/redhat-developer/vscode-redhat-telemetry/blob/HEAD/USAGE_DATA.md#other-extensions).\n\n### Checking telemetry during development\nIn your `.vscode/launch.json`:\n- set the `VSCODE_REDHAT_TELEMETRY_DEBUG` environment variable to `true`, to log telemetry events in the console\n- set the `REDHAT_TELEMETRY_REMOTE_CONFIG_URL` environment variable to the URL of a remote configuration file, if you need to test remote configuration \n\n```json\n{\n  \"name\": \"Run Extension\",\n  \"type\": \"extensionHost\",\n  \"request\": \"launch\",\n  \"args\": [\n    \"--extensionDevelopmentPath=${workspaceFolder}\"\n  ],\n  \"outFiles\": [\n    \"${workspaceFolder}/dist/**/*.js\"\n  ],\n  \"preLaunchTask\": \"${defaultBuildTask}\",\n  \"env\": {\n    \"VSCODE_REDHAT_TELEMETRY_DEBUG\":\"true\",\n    \"REDHAT_TELEMETRY_REMOTE_CONFIG_URL\":\"https://gist.githubusercontent.com/fbricon/cff82f0bd7ff69bf2b9f5f04b1accc50/raw/65b61b7d8845c842a90a8e6a90d852af34934160/telemetry-config.json\"\n  }\n},\n```\n\n\n# How to use from a VS Code web extension\nWhen the VS Code extension runs as a web extension, telemetry should use a webworker specific API. So just change your code so it imports from the dedicated webworker namespace. \n\n```typescript\nimport { getRedHatService, TelemetryService} from \"@redhat-developer/vscode-redhat-telemetry/lib/webworker\";\n```\n\nThe API is identical to the regular node one.\n\nHowever, in order for webpack to compile your web extension, some adjustments are required to the alias and fallback properties:\n\n```js\n/**@type {import('webpack').Configuration}*/\nconst webConfig = {\n  target: 'webworker', // extensions run in a webworker context\n  ...\n  resolve: {\n    ...\n    alias: {\n      'node-fetch': 'whatwg-fetch',\n      'object-hash': 'object-hash/dist/object_hash.js',\n    },\n    fallback: {\n      path: require.resolve('path-browserify'),\n      'node-fetch': require.resolve('whatwg-fetch'),\n      util: require.resolve('util'),\n    },\n  },\n  ...\n};\n```\n\n# Build\nIn a terminal, execute: \n```\nnpm i\n```\nto install the dependencies, then:\n```\nnpm run prepublish\n```\nto build the library\n\n# Information on data transmission during development\n\nWhen the extension sending telemetry is running in `development mode`, the data are sent to the `test.vscode` project on https://segment.com/, or whatever project bound to the optional [segmentWriteDebugKey](#optional-add-a-custom-segment-key-in-packagejson-file).\nAs the transmission is opt-in, unless specifiying it explicitely, no data are transmitted during CI builds.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-developer%2Fvscode-redhat-telemetry","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fredhat-developer%2Fvscode-redhat-telemetry","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fredhat-developer%2Fvscode-redhat-telemetry/lists"}