diff --git a/content/docs/integrations/application-platforms/meta.json b/content/docs/integrations/application-platforms/meta.json new file mode 100644 index 0000000..bbf5ae9 --- /dev/null +++ b/content/docs/integrations/application-platforms/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Application Platforms", + "pages": [ + "vercel" + ] +} diff --git a/content/docs/integrations/application-platforms/static/vercel/WebAnalytics.png b/content/docs/integrations/application-platforms/static/vercel/WebAnalytics.png new file mode 100644 index 0000000..e6400bb Binary files /dev/null and b/content/docs/integrations/application-platforms/static/vercel/WebAnalytics.png differ diff --git a/content/docs/integrations/application-platforms/vercel.mdx b/content/docs/integrations/application-platforms/vercel.mdx new file mode 100644 index 0000000..37375b8 --- /dev/null +++ b/content/docs/integrations/application-platforms/vercel.mdx @@ -0,0 +1,144 @@ +--- +title: Vercel +description: Send Vercel logs, traces, Speed Insights and Web Analytics to Parseable +--- + +The Parseable integration creates Vercel Drains for Parseable Cloud and self-hosted deployments. The setup wizard handles endpoints and authentication headers. + +## What the integration collects + +You can enable any of these signals during installation: + +| Signal | Default dataset | Delivery | +| --- | --- | --- | +| Logs | `vercel_logs` | JSON over HTTP | +| Traces | `vercel_traces` | OTLP/HTTP JSON | +| Speed Insights | `vercel_speed_insights` | JSON over HTTP | +| Web Analytics | `vercel_analytics` | JSON over HTTP | + +Vercel sends each signal to your Parseable ingest endpoint. Parseable configures the drains without proxying or storing telemetry. + +## Prerequisites + +- A Vercel Pro or Enterprise team. Vercel Drains are available on these plans. +- A Parseable Cloud workspace or a self-hosted Parseable deployment reachable from the public internet. +- Datasets for the signals you plan to enable. +- A Parseable API key with ingest-only access to those datasets. See [API keys](/docs/user-guide/api-keys#dataset-scoped-ingestion-key). + +For a self-hosted deployment, expose the Parseable ingest endpoint over HTTPS. An HTTP endpoint sends telemetry and its API key without transport encryption. + +## Install from Vercel + +### 1. Open the integration + +Open the [Parseable integration on Vercel](https://vercel.com/integrations/parseable) and select **Connect Account**. + +### 2. Choose the Vercel scope + +Select the Vercel team and projects that may send telemetry. Choose all projects or limit the integration to specific projects, then approve the requested Drains permission. + +Vercel enforces this project selection. A drain configured for all permitted projects does not receive telemetry from projects outside the integration configuration. + +### 3. Choose the Parseable deployment + +The setup wizard offers two connection types: + +- **Parseable Cloud:** Enter a Parseable Cloud API key. Parseable finds the workspace ingest endpoint. +- **Self-hosted:** Enter the public base URL of your Parseable cluster and a scoped ingest API key. + +The self-hosted URL must start with `https://` or `http://`, must be reachable by the integration and must not redirect to a private or internal network address. + +### 4. Select signals and datasets + +Enable at least one signal. Keep the default dataset names or replace them with datasets already covered by the API key: + +- Logs +- Traces +- Speed Insights +- Web Analytics + +The wizard validates the Parseable connection and tests the proposed Vercel delivery settings before it creates a drain for each enabled signal. + +### 5. Review and finish + +Review the destination and signal-to-dataset mappings, then finish the installation. Parseable creates the drains and returns you to Vercel. + +If any drain fails, the installation removes drains created during that attempt instead of leaving a partial configuration. + +## Verify the installation + +In Vercel, open **Team Settings > Drains**. You should see one Parseable drain per enabled signal. + +Generate traffic or deploy the selected Vercel project, then check the corresponding datasets in Parseable. Data can take a short time to appear. + +For logs, useful Vercel fields can include project, deployment, environment, source, path, status and request identifiers. Traces appear through Parseable's native OpenTelemetry trace ingestion. + +If the integration was limited to selected projects, generate traffic from both selected and unselected projects. Only telemetry from selected projects should appear. + +## Import the Vercel dashboard + +The reusable [Vercel Integration Observability dashboard](https://github.com/parseablehq/dashboards/tree/main/vercel-integration-observability) contains 22 SQL tiles for logs, traces, Speed Insights and Web Analytics. Import `vercel-integration-observability-mixed.json`, then map its four dataset variables to the datasets selected during Vercel installation. Sections for signals you did not enable remain empty. + +![Vercel Web Analytics dashboard in Parseable](./static/vercel/WebAnalytics.png) + +## Update the configuration + +Open the installed Parseable integration in Vercel and select **Configure**. + +1. Enter the API key connected to the installation to verify ownership. +2. Update dataset names. +3. To rotate credentials, enter a replacement API key with ingest access to each configured dataset. +4. Select **Save changes**. + +The integration tests the replacement settings, updates the Vercel drains and then saves the new configuration. Leaving the replacement-key field empty keeps the current key. + +The configuration page keeps the original signal set. Uninstall and reinstall the integration to add or remove signals. + +## Uninstall + +Remove Parseable from the integration settings in Vercel. Vercel stops the associated drains and notifies Parseable that the installation was removed. + +Uninstalling leaves your Parseable datasets and API key intact. Revoke the key in Parseable when you no longer need it. + +## Troubleshooting + +### Installation cannot start + +Start installation from the Parseable listing in Vercel. The redirect URL requires a one-time authorization code and configuration parameters from Vercel. Opening that URL in your browser produces an installation error. + +### Parseable rejects the API key + +- Confirm the key is active and copied without surrounding whitespace. +- Confirm its role grants ingest access to each selected dataset. +- For Parseable Cloud, confirm the key belongs to a running workspace. +- For self-hosted Parseable, confirm the URL points to the ingest endpoint associated with that key. + +### Self-hosted validation fails + +- Confirm the cluster is reachable from the public internet. +- Use the Parseable base URL, without an ingestion path such as `/api/v1/ingest` or `/v1/traces`. +- Use HTTPS with a valid certificate. +- Check firewalls, allowlists, proxies and DNS resolution. +- Private, loopback, link-local and cloud-metadata addresses are rejected. + +### Drain creation or delivery fails + +- Verify the Vercel team uses a Pro or Enterprise plan. +- In **Team Settings > Drains**, inspect the affected drain and its latest delivery error. +- Confirm the target dataset exists and the API key can ingest into it. +- Confirm the selected Parseable endpoint accepts both JSON ingestion and OTLP traces when those signals are enabled. +- Reopen **Configure** to correct dataset mappings or rotate the key. + +### No data appears + +- Generate fresh traffic for a project included in the integration scope. +- Confirm the expected signal was enabled during installation. +- Check the dataset selected for that signal rather than only the default dataset name. +- Confirm the Vercel drain is active and its delivery tests succeed. + +## Security notes + +- Use a dedicated, dataset-scoped ingestion key rather than an administrator or query key. +- Store the key in a secrets manager. Parseable encrypts the saved credential and hides it on the configuration page. +- Vercel sends telemetry to the selected Parseable cluster. +- Parseable leaves customer-owned keys intact during rotation and uninstall. Revoke unused keys from Access Management. diff --git a/content/docs/integrations/index.mdx b/content/docs/integrations/index.mdx index 842f5ee..35e6222 100644 --- a/content/docs/integrations/index.mdx +++ b/content/docs/integrations/index.mdx @@ -207,6 +207,9 @@ Observability pipeline ## Application platforms + +Send logs, traces, Speed Insights, and Web Analytics to Parseable + Ingest Fly.io platform logs and metrics diff --git a/content/docs/integrations/meta.json b/content/docs/integrations/meta.json index a54d5ec..00fb9df 100644 --- a/content/docs/integrations/meta.json +++ b/content/docs/integrations/meta.json @@ -1,6 +1,7 @@ { "title": "Integrations", "pages": [ + "application-platforms", "alerting", "auth", "data-platforms",