mirror of
https://github.com/BillyOutlast/posthog.com.git
synced 2026-02-06 20:31:20 +01:00
94 lines
3.2 KiB
Plaintext
94 lines
3.2 KiB
Plaintext
---
|
|
title: Node.js error tracking installation
|
|
showStepsToc: true
|
|
---
|
|
|
|
import InstallNodePackageManagers from "../../integrate/_snippets/install-node-package-managers.mdx"
|
|
import StepVerifyErrorTracking from "./_snippets/step-verify-error-tracking.mdx"
|
|
import StepUploadSourceMaps from "./_snippets/step-upload-source-maps.tsx"
|
|
|
|
<Steps>
|
|
<Step title="Install PostHog Node.js SDK" badge="required">
|
|
|
|
Install the PostHog Node SDK using the package manager of your choice:
|
|
|
|
<InstallNodePackageManagers />
|
|
|
|
In your app, set your project API key **before** making any calls.
|
|
|
|
```node
|
|
import { PostHog } from 'posthog-node'
|
|
|
|
const client = new PostHog(
|
|
'<ph_project_api_key>',
|
|
{ host: '<ph_client_api_host>' }
|
|
)
|
|
|
|
await client.shutdown() // TIP: On program exit, call shutdown to stop pending pollers and flush any remaining events
|
|
```
|
|
|
|
You can find your project API key and instance address in the [project settings](https://app.posthog.com/project/settings) page in PostHog.
|
|
|
|
> **Note:** As a rule of thumb, we do not recommend hardcoding API keys. Setting it as an environment variable is preferred.
|
|
|
|
</Step>
|
|
|
|
<Step checkpoint title="Verify PostHog is initialized" subtitle="Confirm you can capture events with PostHog">
|
|
|
|
Before proceeding, confirm that you can capture events with PostHog using `client.capture('test_event')`.
|
|
|
|
</Step>
|
|
|
|
<Step title="Configure exception autocapture" badge="recommended">
|
|
|
|
> **Note:** A minimum SDK version of v4.5.2 is required, but we recommend [keeping up to date with the latest version](/docs/sdk-doctor) to ensure you have all of error tracking's features.
|
|
|
|
You can enable exception autocapture when initializing the PostHog client to automatically capture uncaught exceptions and unhandled rejections in your Node app.
|
|
|
|
```node
|
|
import { PostHog } from 'posthog-node'
|
|
|
|
const client = new PostHog(
|
|
'<ph_project_api_key>',
|
|
{ host: '<ph_client_api_host>', enableExceptionAutocapture: true }
|
|
)
|
|
```
|
|
|
|
If you are using the Express framework, you will need to import and call `setupExpressErrorHandler` with your PostHog client and Express app. This is because Express handles uncaught exceptions internally meaning exception autocapture will not work by default.
|
|
|
|
```node file=server.ts
|
|
import express from 'express'
|
|
import { PostHog, setupExpressErrorHandler } from 'posthog-node'
|
|
|
|
const app = express()
|
|
const posthog = new PostHog(PH_API_KEY)
|
|
|
|
setupExpressErrorHandler(posthog, app)
|
|
```
|
|
|
|
> **Note:** Error tracking requires access the file system to process stack traces. Some providers, like Cloudflare Workers, do not support Node.js runtime APIs by default and need to be [included as per their documentation](https://developers.cloudflare.com/workers/runtime-apis/nodejs/#nodejs-compatibility).
|
|
|
|
</Step>
|
|
|
|
<Step title="Manually capture exceptions" badge="optional">
|
|
|
|
If you need to manually capture exceptions, you can do so by calling the `captureException` method:
|
|
|
|
```node
|
|
posthog.captureException(e, 'user_distinct_id', additionalProperties)
|
|
```
|
|
|
|
This is helpful if you've built your own error handling logic or want to capture exceptions normally handled by the framework.
|
|
|
|
</Step>
|
|
|
|
<StepVerifyErrorTracking />
|
|
|
|
<Step title="Upload source maps" badge="optional">
|
|
|
|
<StepUploadSourceMaps urlPath="node" framework="Node.js" />
|
|
|
|
</Step>
|
|
|
|
|
|
</Steps> |