Skip to content

Commit 31e9173

Browse files
petyosipetyosi
committed
Doc updates
1 parent 46a4a2e commit 31e9173

File tree

1 file changed

+125
-87
lines changed

1 file changed

+125
-87
lines changed

‎README.md‎

Lines changed: 125 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,150 +1,175 @@
11
# Pydantic Logfire — Uncomplicated Observability — JavaScript SDK
22

3-
From the team behind [Pydantic](https://pydantic.dev/), **Logfire** is an observability platform built on the same belief as our
4-
open source library — that the most powerful tools can be easy to use.
3+
From the team behind [Pydantic](https://pydantic.dev/), **Logfire** is an
4+
observability platform built on the same belief as our open source library —
5+
that the most powerful tools can be easy to use.
56

67
What sets Logfire apart:
78

8-
- **Simple and Powerful:** Logfire's dashboard is simple relative to the power it provides, ensuring your entire engineering team will actually use it.
9-
- **SQL:** Query your data using standard SQL — all the control and (for many) nothing new to learn. Using SQL also means you can query your data with existing BI tools and database querying libraries.
10-
- **OpenTelemetry:** Logfire is an opinionated wrapper around OpenTelemetry, allowing you to leverage existing tooling, infrastructure, and instrumentation for many common packages, and enabling support for virtually any language. We offer full support for all OpenTelemetry signals (traces, metrics and logs).
9+
- **Simple and Powerful:** Logfire's dashboard is simple relative to the power
10+
it provides, ensuring your entire engineering team will actually use it.
11+
- **SQL:** Query your data using standard SQL — all the control and (for many)
12+
nothing new to learn. Using SQL also means you can query your data with
13+
existing BI tools and database querying libraries.
14+
- **OpenTelemetry:** Logfire is an opinionated wrapper around OpenTelemetry,
15+
allowing you to leverage existing tooling, infrastructure, and instrumentation
16+
for many common packages, and enabling support for virtually any language. We
17+
offer full support for all OpenTelemetry signals (traces, metrics, and logs).
1118

12-
**Feel free to report issues and ask any questions about Logfire in this repository!**
19+
**Feel free to report issues and ask any questions about Logfire in this
20+
repository!**
1321

14-
This repo contains the JavaScript SDK for `logfire` and its documentation; the server application for recording and displaying data is closed source.
22+
This repository contains the JavaScript SDK for `logfire` and its documentation;
23+
the server application for recording and displaying data is closed source.
1524

1625
<img width="1394" alt="Logfire UI with Next.js traces" src="https://github.com/user-attachments/assets/a2a1167b-6bf7-4d6a-8d59-81cb2433c8e9" />
1726

1827
## Usage
1928

20-
Depending on your environment, you can integrate Logfire in several ways. Follow the specific instructions below:
29+
Depending on your environment, you can integrate Logfire in several ways. Follow
30+
the specific instructions below:
2131

2232
### Basic Node.js script
2333

24-
Using logfire from your Node.js script is as simple as [getting a write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/), installing the package, calling configure, and using the provided API. Let's create an empty project:
34+
Using Logfire from your Node.js script is as simple as
35+
[getting a write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/),
36+
installing the package, calling configure, and using the provided API. Let's
37+
create an empty project:
2538

2639
```sh
27-
mkdir test-logfire-js;
28-
cd test-logfire-js;
29-
npm init -y es6 # makes the package.json with `type: module`
40+
mkdir test-logfire-js
41+
cd test-logfire-js
42+
npm init -y es6 # creates package.json with `type: module`
3043
npm install logfire
3144
```
3245

3346
Then, create the following `hello.js` script in the directory:
3447

35-
3648
```js
37-
import * as logfire from 'logfire'
49+
import * as logfire from "logfire";
3850

3951
logfire.configure({
40-
token: 'test-e2e-write-token',
52+
token: "test-e2e-write-token",
4153
advanced: {
42-
baseUrl: 'http://localhost:8000'
54+
baseUrl: "http://localhost:8000",
4355
},
44-
serviceName: 'example-node-script',
45-
serviceVersion: '1.0.0',
46-
})
47-
56+
serviceName: "example-node-script",
57+
serviceVersion: "1.0.0",
58+
});
4859

49-
logfire.info('Hello from Node.js', {
50-
'attribute-key': 'attribute-value'
60+
logfire.info("Hello from Node.js", {
61+
"attribute-key": "attribute-value",
5162
}, {
52-
tags: ['example', 'example2']
53-
})
63+
tags: ["example", "example2"],
64+
});
5465
```
5566

56-
Run the script above with `node hello.js`, and you should see the span being logged in the live view of your Logfire project.
57-
58-
67+
Run the script with `node hello.js`, and you should see the span being logged in
68+
the live view of your Logfire project.
5969

6070
### Cloudflare Workers
6171

62-
First, install the `@pydantic/logfire-cf-workers @pydantic/logfire-api` NPM packages:
63-
64-
> [!NOTE]
65-
> `@pydantic/logfire-cf-workers` wraps the [`@microlabs/otel-cf-workers`](https://github.com/evanderkoogh/otel-cf-workers) NPM package.
72+
First, install the `@pydantic/logfire-cf-workers @pydantic/logfire-api` NPM
73+
packages:
6674

6775
```sh
6876
npm install @pydantic/logfire-cf-workers @pydantic/logfire-api
6977
```
70-
Next, add `compatibility_flags = [ "nodejs_compat" ]` to your wrangler.toml or `"compatibility_flags": ["nodejs_compat"]` if you're using `wrangler.jsonc`.
7178

72-
Add your [Logfire write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/) to your `.dev.vars` file.
79+
Next, add `compatibility_flags = [ "nodejs_compat" ]` to your wrangler.toml or
80+
`"compatibility_flags": ["nodejs_compat"]` if you're using `wrangler.jsonc`.
81+
82+
Add your
83+
[Logfire write token](https://logfire.pydantic.dev/docs/how-to-guides/create-write-tokens/)
84+
to your `.dev.vars` file:
7385

7486
```sh
7587
LOGFIRE_TOKEN=your-write-token
7688
```
7789

78-
For the production deployment, check the [Cloudflare documentation for further details on how to manage and deploy the secrets](https://developers.cloudflare.com/workers/configuration/secrets/).
90+
For production deployment, check the
91+
[Cloudflare documentation for details on managing and deploying secrets](https://developers.cloudflare.com/workers/configuration/secrets/).
7992

80-
One way to do that is through the `npx wrangler` command:
93+
One way to do this is through the `npx wrangler` command:
8194

8295
```sh
8396
npx wrangler secret put LOGFIRE_TOKEN
8497
```
8598

86-
87-
Next, add the necessary instrumentation around your handler. The `tracerConfig` function will extract your write token from the `env` object and provide the necessary configuration for the instrumentation:
88-
99+
Next, add the necessary instrumentation around your handler. The `tracerConfig`
100+
function will extract your write token from the `env` object and provide the
101+
necessary configuration for the instrumentation:
89102

90103
```ts
91-
import * as logfire from '@pydantic/logfire-api';
92-
import { instrument } from '@pydantic/logfire-cf-workers';
93-
104+
import * as logfire from "@pydantic/logfire-api";
105+
import { instrument } from "@pydantic/logfire-cf-workers";
94106

95107
const handler = {
96-
async fetch(): promise<response> {
97-
logfire.info('info span from inside the worker body');
98-
return new response('hello world!');
108+
async fetch(): Promise<Response> {
109+
logfire.info("info span from inside the worker body");
110+
return new Response("hello world!");
99111
},
100-
} satisfies exportedHandler;
112+
} satisfies ExportedHandler;
101113

102114
export default instrument(handler, {
103-
serviceName: 'cloudflare-worker',
104-
serviceNamespace: '',
105-
serviceVersion: '1.0.0',
115+
serviceName: "cloudflare-worker",
116+
serviceNamespace: "",
117+
serviceVersion: "1.0.0",
106118
});
107119
```
108120

109-
A working example can be found in the `examples/cloudflare-worker` directory.
121+
A working example can be found in the `examples/cloudflare-worker` directory.
110122

111-
### Next.js / Vercel
123+
### Next.js/Vercel
112124

113-
Vercel provides a comprehensive OpenTelemetry integration through the `@vercel/otel` package. After following [their integration instructions](https://vercel.com/docs/otel), Add the following env variables to your project:
125+
Vercel provides a comprehensive OpenTelemetry integration through the
126+
`@vercel/otel` package. After following
127+
[their integration instructions](https://vercel.com/docs/otel), add the
128+
following environment variables to your project:
114129

115130
```sh
116131
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
117132
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://logfire-api.pydantic.dev/v1/metrics
118133
OTEL_EXPORTER_OTLP_HEADERS='Authorization=your-write-token'
119134
```
120135

121-
The above will point the instrumentation to Logfire.
136+
This will point the instrumentation to Logfire.
122137

123138
> [!NOTE]
124-
> The Vercel production deployments have a caching mechanism that might prevent the changes from taking effect immediately or spans being reported. If you are not seeing spans in Logfire, you can [clear the data cache for your project](https://vercel.com/docs/data-cache/manage-data-cache).
139+
> Vercel production deployments have a caching mechanism that might prevent
140+
> changes from taking effect immediately or spans from being reported. If you
141+
> are not seeing spans in Logfire, you can
142+
> [clear the data cache for your project](https://vercel.com/docs/data-cache/manage-data-cache).
125143
126-
Optionally, you can use the Logfire API package for creating manual spans. Install the `@pydantic/logfire-api` NPM package and call the respective methods from your server-side code:
144+
Optionally, you can use the Logfire API package for creating manual spans.
145+
Install the `@pydantic/logfire-api` NPM package and call the respective methods
146+
from your server-side code:
127147

128148
```tsx
129-
import * as logfire from '@pydantic/logfire-api'
149+
import * as logfire from "@pydantic/logfire-api";
130150

131151
export default async function Home() {
132-
return logfire.span('A warning span', {}, {
133-
level: logfire.Level.Warning,
152+
return logfire.span("A warning span", {}, {
153+
level: logfire.Level.Warning,
134154
}, async (span) => {
135-
logfire.info('Nested info span');
155+
logfire.info("Nested info span");
136156
// ending the span is necessary to ensure it is reported
137-
span.end()
157+
span.end();
138158
return <div>Hello</div>;
139-
})
159+
});
140160
}
141161
```
142162

143163
A working example can be found in the `examples/nextjs` directory.
144164

165+
#### Next.js client-side instrumentation
166+
167+
The `@vercel/otel` package does not support client-side instrumentation, so few additional steps are necessary to send spans and/or instrument the client-side.
168+
For a working example, refer to the `examples/nextjs-client-side-instrumentation` directory, which instruments the client-side `fetch` calls.
169+
145170
### Express, generic Node instrumentation
146171

147-
For the purposes of the example, we will instrument this simple Express app:
172+
For this example, we will instrument a simple Express app:
148173

149174
```ts
150175
/*app.ts*/
@@ -166,30 +191,32 @@ app.listen(PORT, () => {
166191
});
167192
```
168193

169-
Next, we will install the `logfire` and `dotenv` NPM packages, so that we can keep our Logfire write token in a `.env` file:
194+
Next, install the `logfire` and `dotenv` NPM packages to keep your Logfire write
195+
token in a `.env` file:
170196

171197
```sh
172198
npm install logfire dotenv
173199
```
174200

175201
Add your token to the `.env` file:
176202

177-
178203
```sh
179204
LOGFIRE_TOKEN=your-write-token
180205
```
181206

182-
Afterwards, we will create an `instrumentation.ts` file that will set up the instrumentation. The `logfire` package includes a `configure` function that simplifies the setup:
207+
Then, create an `instrumentation.ts` file to set up the instrumentation. The
208+
`logfire` package includes a `configure` function that simplifies the setup:
183209

184210
```ts
185211
// instrumentation.ts
186-
import * as logfire from 'logfire'
187-
import 'dotenv/config'
212+
import * as logfire from "logfire";
213+
import "dotenv/config";
188214

189-
logfire.configure()
215+
logfire.configure();
190216
```
191217

192-
The `logfire.configure` call should happen before the actual express module imports, so your NPM start script should look something like this (`package.json`):
218+
The `logfire.configure` call should happen before the actual express module
219+
imports, so your NPM start script should look like this (`package.json`):
193220

194221
```json
195222
"scripts": {
@@ -199,36 +226,47 @@ The `logfire.configure` call should happen before the actual express module impo
199226

200227
## Deno
201228

202-
Deno has [built-in support for OpenTelemetry](https://docs.deno.com/runtime/fundamentals/open_telemetry/). The examples directory includes a `Hello world` example that configures Deno OTel export to Logfire through environment variables.
229+
Deno has
230+
[built-in support for OpenTelemetry](https://docs.deno.com/runtime/fundamentals/open_telemetry/).
231+
The examples directory includes a `Hello world` example that configures Deno
232+
OTel export to Logfire through environment variables.
203233

204-
Optionally, you can use the Logfire API package for creating manual spans. Install the `@pydantic/logfire-api` NPM package and call the respective methods from your code.
234+
Optionally, you can use the Logfire API package for creating manual spans.
235+
Install the `@pydantic/logfire-api` NPM package and call the respective methods
236+
from your code.
205237

206-
#### Configuring the instrumentation
238+
### Configuring the instrumentation
207239

208-
The `logfire.configure` function accepts a set of configuration options that control the behavior of the instrumentation. Alternatively, you can [use environment variables](https://logfire.pydantic.dev/docs/reference/configuration/#programmatically-via-configure) to configure the instrumentation.
240+
The `logfire.configure` function accepts a set of configuration options that
241+
control the behavior of the instrumentation. Alternatively, you can
242+
[use environment variables](https://logfire.pydantic.dev/docs/reference/configuration/#programmatically-via-configure)
243+
to configure the instrumentation.
209244

210-
## Trace API
245+
## Trace API
211246

212-
The `@pydantic/logfire-api` exports several convenience wrappers around the OpenTelemetry span creation API. The `logfire` package re-exports those.
247+
The `@pydantic/logfire-api` exports several convenience wrappers around the
248+
OpenTelemetry span creation API. The `logfire` package re-exports these.
213249

214-
The following methods create spans with the respective log levels (ordered by severity):
250+
The following methods create spans with their respective log levels (ordered by
251+
severity):
215252

216-
* `logfire.trace`
217-
* `logfire.debug`
218-
* `logfire.info`
219-
* `logfire.notice`
220-
* `logfire.warn`
221-
* `logfire.error`
222-
* `logfire.fatal`
253+
- `logfire.trace`
254+
- `logfire.debug`
255+
- `logfire.info`
256+
- `logfire.notice`
257+
- `logfire.warn`
258+
- `logfire.error`
259+
- `logfire.fatal`
223260

224-
Each method accepts a message, attributes, and, optionally options that let you specify the span tags. The attributes values must be serializable to JSON.
261+
Each method accepts a message, attributes, and optionally, options that let you
262+
specify the span tags. The attribute values must be serializable to JSON.
225263

226264
```ts
227265
function info(
228-
message: string,
229-
attributes?: Record<string, unknown>,
230-
options?: LogOptions
231-
): void
266+
message: string,
267+
attributes?: Record<string, unknown>,
268+
options?: LogOptions,
269+
): void;
232270
```
233271

234272
## Contributing

0 commit comments

Comments
 (0)