Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance. Project price only 1 $
You can buy this project and download/modify it how often you want.
# IBM Telemetry JS
> JavaScript telemetry tooling for open/inner source projects
[](https://github.com/ibm-telemetry/telemetry-js/blob/main/LICENSE)
[](https://github.com/carbon-design-system/carbon/blob/master/CONTRIBUTING.md)
[](https://npmjs.org/package/@ibm/telemetry-js)
[](https://npmjs.org/package/@ibm/telemetry-js)
[](https://sonarcloud.io/dashboard?id=ibm-telemetry_telemetry-js)
[](https://github.com/ibm-telemetry/telemetry-js/actions/workflows/ci-checks.yml)
## Quality metrics
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
[](https://sonarcloud.io/summary/new_code?id=ibm-telemetry_telemetry-js)
## Overview
IBM Telemetry collects anonymized usage data for open source and inner source packages when they
have been instrumented with this JavaScript tooling. The data is reported back to a central server
so package maintainers can analyze usage and make improvements.
IBM Telemetry uses [OpenTelemetry](https://opentelemetry.io) as the foundation of its data transport
format.
Find out more detailed documentation and guidelines by choosing from the following sections what
best describes your use case:
- [I use a package that is collecting data via IBM Telemetry](#ibm-telemetry-collection-basics)
- [I have a package that I want to onboard to IBM Telemetry](#onboarding-a-package-to-ibm-telemetry)
- [I don't work for IBM. Can I still use this?](#i-dont-work-for-ibm-can-i-still-use-this)
## IBM Telemetry collection basics
If you're reading this section, you're likely using a package and have noticed that it is collecting
telemetry data using IBM Telemetry. We call that an "instrumented package". Here's what you need to
know about how that works:
- Telemetry data collection runs on CI servers, like GitHub Actions, Travis CI, or Jenkins. It never
runs locally on a developer's machine.
- When `npm install` (or equivalent) is run on the CI server (resulting in the instrumented package
getting installed), IBM Telemetry gets installed too and runs a script which analyzes your source
code and captures data about your usage of the instrumented package.
- This data is fully anonymized and reported back to a server at IBM.
- For more details about exactly what is captured and how sensitive data is anonymized, keep
reading.
- Though IBM Telemetry is installed as a regular dependency in the instrumented package, it has no
exports and therefore **does not impact your project's source code or build output in any way.**
Said differently: This is not a runtime package. It has no "shippable code". It is static source
code analysis performed during builds and nothing more.
The point of capturing this data is to help the open source and inner source maintainers within IBM
by giving them meaningful insights and metrics based on actual data. IBM Telemetry's purpose is to
enable data-driven decision-making to enable maintainers to focus on features that are actually used
by developers like you.
### What data gets collected?
Depending on the nature of the instrumented package and its telemetry configuration, IBM Telemetry
may capture the following data about your project:
**General**
- Date and time of collection
- A de-identified version of your project's git repository URL
- A de-identified version of your project's most recent Git commit hash
- De-identified versions of the branches and tags associated with that commit hash
**NPM data**
- A de-identified version of your project's name (as defined in your package.json file)
- Your project's version (as defined in package.json) with any identifiable parts removed
- De-identified names and versions of your project's dependencies
**JSX data**
- JSX elements (aka components) imported by your project from the instrumented package and details
about the elements’ attributes (aka props) including names, values, and import paths.
Element attribute names that haven't been **specifically configured** by the instrumented package to
be collected will be anonymized before collection.
Boolean and number values will be captured for allowed attribute names. String values that haven't
been **specifically configured** by the instrumented package and other value types (such as complex
objects or variable names) are also anonymized. This means your project-specific data supplied to
JSX elements will never be captured.
All sensitive data that may contain confidential or personally identifiable information that gets
collected by the IBM Telemetry JS tooling gets anonymized/de-identified prior to storage in our
database, see [anonymizing](#anonymizing--de-identifying).
### When does data get collected?
Telemetry collection runs exclusively in CI environments. Collection will never happen on local
development environments or on projects that aren't configured to run automated scripts on a CI
environment (GitHub actions, Travis CI, etc.)
During a build or any other CI operation that installs package dependencies (`npm install`,
`yarn install`, ...), IBM telemetry will run as a background process and perform data collection.
### Opting out of IBM Telemetry data collection
IBM Telemetry will collect metric data for instrumented packages by default. If your project is
installing an IBM Telemetry-instrumented package and you want to opt-out of metric collection, set
the following environment variable to prevent **any and all** data from being collected in your
project.
#### Unix, Linux, MacOS, BSD, etc.
```sh
IBM_TELEMETRY_DISABLED='true'
```
#### Windows (powershell)
```powershell
$Env:IBM_TELEMETRY_DISABLED='true'
```
### Anonymizing / de-identifying
When data is to be de-identified, it is hashed using the SHA-256 cryptographic function, meaning an
instrumented package owner can query for specific known names/values but can never recover original
values from the stored data in the database.
When data is to be anonymized, it is redacted/substituted in a way where its original value can
never be recovered, and there is no meaningful way to query the data to ascertain its value.
As a general philosophy, we favor anonymizing fields over de-identifying them.
## Onboarding a package to IBM Telemetry
### 1. Obtain a project ID from the IBM Telemetry team by opening an issue [here](https://github.com/ibm-telemetry/telemetry-js/issues/new/choose).
The IBM Telemetry team will assign you a project ID to include in your `telemetry.yml` config file.
### 2. Create a `telemetry.yml` config file.
> [!IMPORTANT] This config file needs to be included in your published NPM package!
This file defines what types of metrics will be captured for your project as well as some general
configuration settings.
See the [telemetry config schema](https://github.com/ibm-telemetry/telemetry-config-schema) for a
detailed explanation of all available configuration options.
Sample:
```yaml path="sample-telemetry.yml"
# yaml-language-server: $schema=https://unpkg.com/@ibm/telemetry-config-schema@1/dist/config.schema.json
version: 1
projectId: ''
endpoint: 'https://example.com/v1/metrics'
collect:
npm:
dependencies: null
jsx:
elements:
allowedAttributeNames:
- 'size'
- 'title'
- 'etc.'
allowedAttributeStringValues:
- 'small'
- 'medium'
- 'large'
- 'title1'
- 'title2'
- 'etc.'
```
> **Note**: Though this file can live anywhere within your project, it is customary to place it at
> the root level.
Optionally, use the
[IBM Telemetry Js Config Generator](https://www.npmjs.com/package/@ibm/telemetry-js-config-generator)
script to automatically generate the config file. Remember to verify that the generated output is
correct before using the config file.
### 3. Install `@ibm/telemetry-js` dependency.
> **Note**: This must be installed as a regular dependency, not a dev dependency in the instrumented
> project.
`npm install @ibm/telemetry-js`
or
`yarn add @ibm/telemetry-js`
### 4. Add a `postinstall` script to your `package.json` file.
The `postinstall` script runs telemetry collection anytime your package gets installed inside of
another project.
```jsonc path="package.json"
// ...
"scripts": {
// ...
"postinstall": "ibmtelemetry --config=path/to/your/telemetry.yml"
}
// ...
```
Make sure the `--config` option points to your `telemetry.yml` file within your package.
### 5. Add telemetry collection notice to your docs.
You'll want to be as transparent as possible about telemetry collection and the data that is being
stored. You should strongly consider adding an informational paragraph to your docs (usually the
README) as follows:
```markdown
## IBM Telemetry
This package uses IBM Telemetry to collect metrics data. By installing this package as a dependency
you are agreeing to telemetry collection. To opt out, see
[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
For more information on the data being collected, please see the
[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).
```
Preview notice
## IBM Telemetry
This package uses IBM Telemetry to collect metrics data. By installing this package as a dependency
you are agreeing to telemetry collection. To opt out, see
[Opting out of IBM Telemetry data collection](https://github.com/ibm-telemetry/telemetry-js/tree/main#opting-out-of-ibm-telemetry-data-collection).
For more information on the data being collected, please see the
[IBM Telemetry documentation](https://github.com/ibm-telemetry/telemetry-js/tree/main#ibm-telemetry-collection-basics).
### 6. Publish a new version of your package.
Package consumers need to install a version of your package that includes both the config file and
post-install script in order for telemetry collection to occur.
### 7. Done!
Whenever consumers pick up a version of your package that includes the config file and post-install
script, telemetry collection will run and collect metrics.
## I don't work for IBM. Can I still use this?
Yes! This package can send its output to any OpenTelemetry-compatible collector endpoint via the
standard `v1/metrics`
[Rest API endpoint](https://opentelemetry.io/docs/specs/otlp/#otlphttp-request). All you need to do
is specify your collector endpoint's URL in the `endpoint` configuration setting in your
`telemetry.yml` file.
## Accessing metrics
Coming soon!
