Learn how to set up telemetry for your app so you can send logging information to an external service.
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 and Sentry 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 Developer Terms and Developer Beta Terms.
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.
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.
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.
telemetry-hsmeta.json
The code block below demonstrates an example telemetry-hsmeta.json file configured for Sentry:
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.
typerequired
String
The type of component, which should be telemetry in this case.
configrequired
Object
An object containing the configuration details. See the sub-properties listed in the rows below.
providerTyperequired
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.
If you opt for a custom backend provider, you should also set the endpointUrl field detailed below.
datasetNamerequired
String
A label that will be associated with your log data, if your provider supports that option. When exportFormat is OTLP_LOGS, this value is sent as the OpenTelemetry service.name, so it appears as the service name in providers such as Datadog.
logTypesrequired
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:
API_CALL
EXTENSION_LOG
EXTENSION_RENDER
DATA_FETCH
ENDPOINT_FUNCTION
APP_FUNCTION
WEBHOOKS
APP_SETTINGS
CRM_LEGACY_CARD
.
logLevelsrequired
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.
The URL must be an absolute https URL with a host, and it can’t include credentials.
Omit this field if you’re using Sentry or Honeycomb as your telemetry provider.
bearerAuthEnabled
Boolean
Set to true to forward your TELEMETRY_SECRET on each request to your custom backend endpoint, using the header selected by the authScheme field (Authorization: Bearer by default). When omitted, the secret is not forwarded.
Only applicable when providerType is set to CUSTOM_BACKEND.
authScheme
String
The header used to send your TELEMETRY_SECRET to your custom backend endpoint. Supported values are:
SPLUNK: sends Authorization: Splunk <TELEMETRY_SECRET>. Use this for Splunk OTLP inputs that authenticate with a Splunk HEC token, such as Splunk Connect for OTLP or the Splunk OpenTelemetry Collector.
DATADOG: sends dd-api-key: <TELEMETRY_SECRET> and no Authorization header. Use this for Datadog’s OTLP logs intake.
When omitted, BEARER is used.
Only applicable when providerType is set to CUSTOM_BACKEND. The secret is only sent when bearerAuthEnabled is true.
DATADOG requires providerType set to CUSTOM_BACKEND, exportFormat set to OTLP_LOGS, and bearerAuthEnabled set to true. Your project build will fail if the configuration doesn’t meet these requirements.
exportFormat
String
The wire format used to send telemetry data to your custom backend endpoint. Supported values are:
DEFAULT: the default format.
OTLP: sends the OpenTelemetry traces signal in protobuf format.
OTLP_LOGS: sends the OpenTelemetry logs signal in protobuf format, with the Content-Type: application/x-protobuf header. Set endpointUrl to your provider’s OTLP logs path, which usually ends in /v1/logs.
When omitted, DEFAULT is used.
Only applicable when providerType is set to CUSTOM_BACKEND.
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.
If you’re using Datadog, you’ll add a Datadog API key (not an application key) as a secret.
If you’re using Splunk, you’ll add a Splunk HEC token as a secret.
If you’re using another custom backend, you’ll add the token your endpoint expects as a secret.
Locate a Sentry DSN
If you’re using Sentry, follow the steps below to get your DSN:
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:
In your app’s telemetry-hsmeta.json file, set endpointUrl to the OTLP logs intake endpoint for your Datadog site. For the US1 site, this is https://otlp.datadoghq.com/v1/logs. Other Datadog sites use a different host. See Datadog’s OTLP logs documentation to find the endpoint for your site.
The code block below demonstrates an example telemetry-hsmeta.json file configured for Datadog:
In Datadog, your logs appear under the service set by datasetName. Each log entry’s status matches the level your extension logged it at. For example, logger.error() logs appear with the Error status.
Please note: if Datadog rejects the key or URL with a 401 or 403 response, HubSpot will disable the telemetry configuration and logs will no longer be sent to your endpoint. If you encounter a 403, confirm that the endpointUrl matches your Datadog site.
Send logs to Splunk
To send logs to Splunk, you’ll use a custom backend with the OTLP logs format and the SPLUNK auth scheme.
Create a Splunk HEC token, or copy an existing one. The token must be allowed to write to the target index, or Splunk rejects the payload.
Once you’ve obtained your provider’s key, run the following command to add the value as a secret. When prompted for the name of the secret, you must use TELEMETRY_SECRET for log data to be synced correctly.
hs app secrets add
Last modified on November 18, 2026
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.