Document reportError

Add note about CF testing. Fixes #25

Author: petyosi

.changeset/famous-toes-punch.md

@@ -0,0 +1,5 @@
+---
+"@pydantic/logfire-api": patch
+---
+
+logfire.reportError - documentation and setting correct span type

.changeset/pink-buses-fry.md

@@ -0,0 +1,5 @@
+---
+"@pydantic/logfire-api": patch
+---
+
+Document and slightly enhance the `reportError` function.

README.md

@@ -122,6 +122,28 @@ export default instrument(handler, {
 
 A working example can be found in the `examples/cloudflare-worker` directory.
 
+Note: if you're testing your worker with Vitest, you need to add the following additional configuration to your `vitest.config.mts`:
+
+```
+export default defineWorkersConfig({
+  test: {
+    deps: {
+      optimizer: {
+        ssr: {
+          enabled: true,
+          include: ['@pydantic/logfire-cf-workers'],
+        },
+      },
+    },
+    poolOptions: {
+      workers: {
+        // ...
+      },
+    },
+  },
+});
+```
+
 ### Next.js/Vercel
 
 Vercel provides a comprehensive OpenTelemetry integration through the
@@ -271,6 +293,18 @@ function info(
 ): void;
 ```
 
+### Reporting errors
+
+In addition to `trace`, `debug`, the Logfire API exports a `reportError` function that accepts a message and a JavaScript `Error` object. It will extract the necessary details from the error and create a span with the `error` level.
+
+```ts
+try {
+  1 / 0
+} catch (error) {
+  logfire.reportError("An error occurred", error);
+}
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.

examples/node/index.ts

@@ -5,12 +5,7 @@ logfire.configure({
   serviceName: 'example-node-script',
   serviceVersion: '1.0.0',
   environment: 'staging',
-  token: 'pylf_v1_eu_fcksvB6FNdWKZ3xGbrG8g8GXHFqPfFXgtRgnZdvV6PCj',
   diagLogLevel: logfire.DiagLogLevel.DEBUG,
-  codeSource: {
-    repository: 'https://github.com/pydantic/pydantic',
-    revision: 'master',
-  },
 })
 
 
@@ -27,3 +22,12 @@ logfire.span('Hello from Node.js, {next_player}', {
 }, (span) => {
   span.end()
 })
+
+if (process.env.TRIGGER_ERROR) {
+  try {
+    throw new Error('This is an error for testing purposes');
+  } catch (error) {
+    logfire.reportError("An error occurred", error as Error);
+    console.error("An error occurred:", error);
+  }
+}

packages/logfire-api/src/index.ts

@@ -119,13 +119,23 @@ export function warning(message: string, attributes: Record<string, unknown> = {
   log(message, attributes, { ...options, level: Level.Warning })
 }
 
+/**
+ * Use this method to report an error to Logfire.
+ * Captures the error stack trace and message in the respective semantic attributes and sets the correct level and status.
+ */
 export function reportError(message: string, error: Error, extraAttributes: Record<string, unknown> = {}) {
-  const span = startSpan(message, {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    [ATTR_EXCEPTION_MESSAGE]: error.message ?? 'error',
-    [ATTR_EXCEPTION_STACKTRACE]: error.stack,
-    ...extraAttributes,
-  })
+  const span = startSpan(
+    message,
+    {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      [ATTR_EXCEPTION_MESSAGE]: error.message ?? 'error',
+      [ATTR_EXCEPTION_STACKTRACE]: error.stack,
+      ...extraAttributes,
+    },
+    {
+      level: Level.Error,
+    }
+  )
 
   span.recordException(error)
   span.setStatus({ code: SpanStatusCode.ERROR })