> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: 344efd67-ec9d-4a7b-8483-8c3be2e14c99
---

# Add telemetry

> Learn how to set up telemetry for your app so you can send logging information to an external service.

export const RequiredIndicator = () => {
  return <span className="required-indicator">
      required
    </span>;
};

<style>
  {`
    .table-key, .table-key div, .table-key p {
      margin: 0;
      font-size: 14px;
    }
    code {
      text-wrap:nowrap!important;
    }
    `}
</style>

You can set up telemetry for your app, which acts as a log sink to pipe out log data to an external observability provider. [Honeycomb](https://www.honeycomb.io/) and [Sentry](https://sentry.io/welcome/) are supported as third-party providers.

You can also specify a custom backend with an endpoint URL pointed at a specific backend provider of your choice. Note that using a custom backend provider for app telemetry is currently in beta, and is subject to HubSpot's <a href="https://legal.hubspot.com/developer-terms">Developer Terms</a> and <a href="https://legal.hubspot.com/developerbetaterms">Developer Beta Terms</a>.

## Create and set up telemetry component files

In your project's `src/app/` directory, create a `telemetry/` directory, then add a `telemetry-hsmeta.json` configuration file within it.

```shell theme={null}
└── src/
    └── app/
        └── telemetry/
            └── telemetry-hsmeta.json
```

Edit the `telemetry-hsmeta.json` file to configure your provider, log level settings, and more. An example file is provided below, along with a table that details each of the available fields.

<Warning>
  **Please note**: by default, all log types and levels will be synced with your provider via the `logTypes` and `logLevels` fields, which may result in a very high volume of data being sent. It's strongly recommended you start with configuring only the log types you're interested in, and setting the log levels to filter for errors only.
</Warning>

### telemetry-hsmeta.json

The code block below demonstrates an example `telemetry-hsmeta.json` file configured for Sentry:

```json theme={null}
{
  "uid": "telemetry",
  "type": "telemetry",
  "config": {
    "providerType": "SENTRY",
    "datasetName": "my-app-telemetry",
    "logTypes": [
      "API_CALL",
      "EXTENSION_LOG",
      "EXTENSION_RENDER",
      "DATA_FETCH",
      "ENDPOINT_FUNCTION",
      "APP_FUNCTION",
      "WEBHOOKS",
      "APP_SETTINGS",
      "CRM_LEGACY_CARD"
    ],
    "logLevels": ["ERROR", "WARN", "INFO"]
  }
}
```

| Field                                | Type   | Description                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid` <RequiredIndicator />          | String | A unique identifier for your telemetry configuration. This can be set to any value, but it will appear in your project settings in your account, so it should be different from other `uid` values of other app components.                                                                                                                                             |
| `type` <RequiredIndicator />         | String | The type of component, which should be `telemetry` in this case.                                                                                                                                                                                                                                                                                                        |
| `config` <RequiredIndicator />       | Object | An object containing the configuration details. See the sub-properties listed in the rows below.                                                                                                                                                                                                                                                                        |
| `providerType` <RequiredIndicator /> | String | The name of your third-party telemetry provider, which can be `SENTRY`, `HONEYCOMB`, or you can set this value to `CUSTOM_BACKEND` to propagate data to a specific backend provider of your choice. <br /> <br /> If you opt for a custom backend provider, you should also set the `endpointUrl` field detailed below.                                                 |
| `datasetName` <RequiredIndicator />  | String | A label that will be associated with your log data, if your provider supports that option.                                                                                                                                                                                                                                                                              |
| `logTypes` <RequiredIndicator />     | Array  | A list of log types sent to your external provider. By default, all logs are propagated to your provider. The available log types include: <ul><li>`API_CALL`</li><li>`EXTENSION_LOG`</li><li>`EXTENSION_RENDER`</li><li>`DATA_FETCH`</li><li>`ENDPOINT_FUNCTION`</li><li>`APP_FUNCTION`</li><li>`WEBHOOKS`</li><li>`APP_SETTINGS`</li><li>`CRM_LEGACY_CARD`</li></ul>. |
| `logLevels` <RequiredIndicator />    | Array  | A list of severity levels to filter logs by. Supported log levels are: `"ERROR"`, `"WARN"`, `"INFO"`, `"TRACE"`, and `"DEBUG"`                                                                                                                                                                                                                                          |
| `endpointUrl`                        | String | If you specified a custom backend via the `CUSTOM_BACKEND` value as your `providerType`, use this field to provide the URL to your custom backend provider, following your provider's documentation to get the URL that's specific to your account. <br /> <br /> Omit this field if you're using Sentry or Honeycomb as your telemetry provider.                       |

## Add external authentication as a secret via the CLI

In addition to creating the `telemetry-hsmeta.json` configuration file above, you'll also need to add a secret that corresponds to the authentication key for your provider:

* If you're using Sentry, you'll add the DSN (Data Source Name) as a secret.
* If you're using Honeycomb, you'll add an API key as a secret.

### Locate a Sentry DSN

If you're using Sentry, follow the steps below to get your DSN:

* Log into your [Sentry account](https://sentry.io/welcome/auth/login/).
* Navigate to your project's settings.
* Under the *Client Keys* or *DSN* section, you'll find a unique DSN for your project. It should resemble the following:

```
https://sentry-key@sentry-identifier.ingest.us.sentry.io/project-id
```

### Locate a Honeycomb API key

If you're using Honeycomb as your external observability provider, an API key is used to authenticate and forward data. This API key is associated with your specific Honeycomb account and project.

To generate a Honeycomb API key:

* Log into your [Honeycomb account](https://ui.honeycomb.io/login).
* Navigate to your project settings.
* Find the *API Keys* section and generate a new key.
* Copy the generated API key.

### Add a secret using the HubSpot CLI

Once you've obtained either your Sentry DSN or Honeycomb API key, run the following command to add the value as a secret. When prompted for the name of the secret, you <u>must</u> use `TELEMETRY_SECRET` for log data to be synced correctly.

```shell theme={null}
hs app secrets add
```