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..997d74c --- /dev/null +++ b/content/docs/integrations/application-platforms/vercel.mdx @@ -0,0 +1,166 @@ +--- +title: Vercel +description: Send Vercel logs, traces, Speed Insights and Web Analytics to Parseable +--- + +import { Step, Steps } from 'fumadocs-ui/components/steps'; + +Vercel is a frontend cloud platform for building and running web applications, serverless functions and edge workloads. Once those applications are live, their logs, traces, web vitals and analytics events are useful outside the Vercel dashboard as well, especially when teams want to query them with the rest of their telemetry. + +The Parseable integration creates Vercel Drains for Parseable Cloud and self-hosted deployments. The setup wizard handles endpoints, dataset mapping and authentication headers, so you do not have to create each drain by hand. + +## 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 | +| Speed Insights | `vercel_speed_insights` | JSON over HTTP | +| Web Analytics | `vercel_analytics` | JSON over HTTP | + +Vercel sends each enabled signal to your Parseable ingest endpoint. Parseable stores the incoming records in the dataset selected for that signal. + +## 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 + + + + +### Open the integration + +Open the [Parseable integration on Vercel](https://vercel.com/integrations/parseable) and select **Connect Account**. + + + + +### 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. + + + + +### 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. + + + + +### 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. + + + + +### 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 panels 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",