Skip to content

Commit d0aa7df

Browse files
thesollyztothmano
thesollyz
and
tothmano
authored
Full docs for SDKs (#101)
Co-authored-by: Mano Toth <mano@axiom.co> Co-authored-by: Mano Toth <71388581+tothmano@users.noreply.github.com>
1 parent cfdc403 commit d0aa7df

File tree

7 files changed

+499
-13
lines changed

7 files changed

+499
-13
lines changed

‎guides/go.mdx

Lines changed: 90 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,93 @@
11
---
22
title: 'Send data from Go app to Axiom'
3-
description: 'This guide explains how to send data from a Go app to Axiom.'
3+
description: 'This page explains how to send data from a Go app to Axiom.'
44
sidebarTitle: Golang
5-
url: "https://github.com/axiomhq/axiom-go"
6-
---
5+
---
6+
7+
To send data from a Go app to Axiom, use the Axiom Go SDK.
8+
9+
<Note>
10+
The Axiom Go SDK is an open-source project and welcomes your contributions. For more information, see the [GitHub repository](https://github.com/axiomhq/axiom-go).
11+
</Note>
12+
13+
import Prerequisites from "/snippets/standard-prerequisites.mdx"
14+
15+
<Prerequisites />
16+
17+
## Install SDK
18+
19+
To install the SDK, run the following:
20+
21+
```shell
22+
go get github.com/axiomhq/axiom-go/axiom
23+
```
24+
25+
Import the package:
26+
27+
```go
28+
import "github.com/axiomhq/axiom-go/axiom"
29+
```
30+
31+
If you use the [Axiom CLI](/reference/cli), run `eval $(axiom config export -f)` to configure your environment variables. Otherwise, [create an API token](/reference/tokens) and export it as `AXIOM_TOKEN`.
32+
33+
Alternatively, configure the client using [options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) passed to the `axiom.NewClient` function:
34+
35+
```go
36+
client, err := axiom.NewClient(
37+
axiom.SetPersonalTokenConfig("AXIOM_TOKEN"),
38+
)
39+
```
40+
41+
## Use client
42+
43+
Create and use a client in the following way:
44+
45+
```go
46+
package main
47+
48+
import (
49+
"context"
50+
"fmt"
51+
"log"
52+
53+
"github.com/axiomhq/axiom-go/axiom"
54+
"github.com/axiomhq/axiom-go/axiom/ingest"
55+
)
56+
57+
func main() {
58+
ctx := context.Background()
59+
60+
client, err := axiom.NewClient()
61+
if err != nil {
62+
log.Fatal(err)
63+
}
64+
65+
if _, err = client.IngestEvents(ctx, "my-dataset", []axiom.Event{
66+
{ingest.TimestampField: time.Now(), "foo": "bar"},
67+
{ingest.TimestampField: time.Now(), "bar": "foo"},
68+
}); err != nil {
69+
log.Fatal(err)
70+
}
71+
72+
res, err := client.Query(ctx, "['my-dataset'] | where foo == 'bar' | limit 100")
73+
if err != nil {
74+
log.Fatal(err)
75+
} else if res.Status.RowsMatched == 0 {
76+
log.Fatal("No matches found")
77+
}
78+
79+
rows := res.Tables[0].Rows()
80+
if err := rows.Range(ctx, func(_ context.Context, row query.Row) error {
81+
_, err := fmt.Println(row)
82+
return err
83+
}); err != nil {
84+
log.Fatal(err)
85+
}
86+
}
87+
```
88+
89+
For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-go/tree/main/examples).
90+
91+
## Adapters
92+
93+
To use a logging package, see the [adapters in GitHub](https://github.com/axiomhq/axiom-go/tree/main/adapters).

‎guides/javascript.mdx

Lines changed: 94 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,97 @@
11
---
22
title: 'Send data from JavaScript app to Axiom'
3-
description: 'This guide explains how to send data from a JavaScript app to Axiom.'
3+
description: 'This page explains how to send data from a JavaScript app to Axiom.'
44
sidebarTitle: JavaScript
5-
url: "https://github.com/axiomhq/axiom-js"
6-
---
5+
---
6+
7+
To send data from a JavaScript app to Axiom, use the Axiom JavaScript SDK.
8+
9+
<Note>
10+
The Axiom JavaScript SDK is an open-source project and welcomes your contributions. For more information, see the [GitHub repository](https://github.com/axiomhq/axiom-js).
11+
</Note>
12+
13+
import Prerequisites from "/snippets/standard-prerequisites.mdx"
14+
15+
<Prerequisites />
16+
17+
## Install SDK
18+
19+
To install the SDK, run the following:
20+
21+
```shell
22+
npm install @axiomhq/js
23+
```
24+
25+
If you use the [Axiom CLI](/reference/cli), run `eval $(axiom config export -f)` to configure your environment variables. Otherwise, [create an API token](/reference/tokens) and export it as `AXIOM_TOKEN`.
26+
27+
You can also configure the client using options passed to the constructor of the client:
28+
29+
```ts
30+
import { Axiom } from '@axiomhq/js';
31+
32+
const axiom = new Axiom({
33+
token: process.env.AXIOM_TOKEN,
34+
});
35+
```
36+
37+
## Send data
38+
39+
The following example sends data to Axiom:
40+
41+
```ts
42+
axiom.ingest('DATASET_NAME', [{ foo: 'bar' }]);
43+
await axiom.flush();
44+
```
45+
46+
The client automatically batches events in the background. In most cases, you only want to call `flush()` before your application exits.
47+
48+
## Query data
49+
50+
The following example queries data from Axiom:
51+
52+
```ts
53+
const res = await axiom.query(`['DATASET_NAME'] | where foo == 'bar' | limit 100`);
54+
console.log(res);
55+
```
56+
57+
For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-js/tree/main/examples).
58+
59+
## Capture errors
60+
61+
To capture errors, pass a method `onError` to the client:
62+
63+
```ts
64+
let client = new Axiom({
65+
token: '',
66+
...,
67+
onError: (err) => {
68+
console.error('ERROR:', err);
69+
}
70+
});
71+
```
72+
73+
By default, `onError` is set to `console.error`.
74+
75+
## Create annotations
76+
77+
The following example creates an annotation:
78+
79+
```ts
80+
import { annotations } from '@axiomhq/js';
81+
82+
const client = new annotations.Service({ token: process.env.AXIOM_TOKEN });
83+
84+
await annotations.create({
85+
type: 'deployment',
86+
datasets: ['DATASET_NAME'],
87+
title: 'New deployment',
88+
description: 'Deployed version 1.0.0',
89+
})
90+
```
91+
92+
## Log from Node.js
93+
94+
While the Axiom JavaScript client works on both the backend and the browsers, Axiom provides transports for some of the popular loggers:
95+
96+
- [Pino](/guides/pino)
97+
- [Winston](/guides/winston)

‎guides/pino.mdx

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
title: 'Axiom transport for Pino logger'
3+
description: 'This page explains how to send data from a Node.js app to Axiom through Pino.'
4+
sidebarTitle: Pino
5+
tags: ['js', 'pino', 'winston', 'node', 'javascript', 'typescript', 'ts']
6+
---
7+
8+
import Prerequisites from "/snippets/standard-prerequisites.mdx"
9+
10+
<Prerequisites />
11+
12+
## Install SDK
13+
14+
To install the SDK, run the following:
15+
16+
```shell
17+
npm install @axiomhq/pino
18+
```
19+
20+
## Create Pino logger
21+
22+
The example below creates a Pino logger with Axiom configured:
23+
24+
```ts
25+
import pino from 'pino';
26+
27+
const logger = pino(
28+
{ level: 'info' },
29+
pino.transport({
30+
target: '@axiomhq/pino',
31+
options: {
32+
dataset: process.env.AXIOM_DATASET,
33+
token: process.env.AXIOM_TOKEN,
34+
},
35+
}),
36+
);
37+
```
38+
39+
After setting up the Axiom transport for Pino, use the logger as usual:
40+
41+
```js
42+
logger.info('Hello from Pino!');
43+
```
44+
45+
## Examples
46+
47+
For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-js/tree/main/examples/pino).

‎guides/python.mdx

Lines changed: 101 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,104 @@
11
---
22
title: 'Send data from Python app to Axiom'
3-
description: 'This guide explains how to send data from a Python app to Axiom.'
3+
description: 'This page explains how to send data from a Python app to Axiom.'
44
sidebarTitle: Python
5-
url: "https://github.com/axiomhq/axiom-py"
6-
---
5+
---
6+
7+
import Prerequisites from "/snippets/standard-prerequisites.mdx"
8+
9+
To send data from a Python app to Axiom, use the Axiom Python SDK.
10+
11+
<Note>
12+
The Axiom Python SDK is an open-source project and welcomes your contributions. For more information, see the [GitHub repository](https://github.com/axiomhq/axiom-py).
13+
</Note>
14+
15+
<Prerequisites />
16+
17+
## Install SDK
18+
19+
<CodeGroup>
20+
21+
```shell Linux / MacOS
22+
python3 -m pip install axiom-py
23+
```
24+
25+
```shell Windows
26+
py -m pip install axiom-py
27+
```
28+
29+
```shell pip
30+
pip3 install axiom-py
31+
```
32+
33+
</CodeGroup>
34+
35+
If you use the [Axiom CLI](/reference/cli), run `eval $(axiom config export -f)` to configure your environment variables. Otherwise, [create an API token](/reference/tokens) and export it as `AXIOM_TOKEN`.
36+
37+
You can also configure the client using options passed to the client constructor:
38+
39+
```py
40+
import axiom_py
41+
42+
client = axiom_py.Client("API_TOKEN")
43+
```
44+
45+
## Use client
46+
47+
```py
48+
import axiom_py
49+
import rfc3339
50+
from datetime import datetime,timedelta
51+
52+
client = axiom_py.Client()
53+
54+
client.ingest_events(
55+
dataset="DATASET_NAME",
56+
events=[
57+
{"foo": "bar"},
58+
{"bar": "baz"},
59+
])
60+
client.query(r"['DATASET_NAME'] | where foo == 'bar' | limit 100")
61+
```
62+
63+
For more examples, see the [examples in GitHub](https://github.com/axiomhq/axiom-py/tree/main/examples/client_example.py).
64+
65+
## Example with `AxiomHandler`
66+
67+
The example below uses `AxiomHandler` to send logs from the `logging` module to Axiom:
68+
69+
```python
70+
import axiom_py
71+
from axiom_py.logging import AxiomHandler
72+
import logging
73+
74+
def setup_logger():
75+
client = axiom_py.Client()
76+
handler = AxiomHandler(client, "DATASET_NAME")
77+
logging.getLogger().addHandler(handler)
78+
```
79+
80+
For a full example, see [GitHub](https://github.com/axiomhq/axiom-py/tree/main/examples/logger_example.py).
81+
82+
## Example with `structlog`
83+
84+
The example below uses [structlog](https://github.com/hynek/structlog) to send logs to Axiom:
85+
86+
```python
87+
from axiom_py import Client
88+
from axiom_py.structlog import AxiomProcessor
89+
90+
def setup_logger():
91+
client = Client()
92+
93+
structlog.configure(
94+
processors=[
95+
# ...
96+
structlog.processors.add_log_level,
97+
structlog.processors.TimeStamper(fmt="iso", key="_time"),
98+
AxiomProcessor(client, "DATASET_NAME"),
99+
# ...
100+
]
101+
)
102+
```
103+
104+
For a full example, see [GitHub](https://github.com/axiomhq/axiom-py/tree/main/examples/structlog_example.py).

0 commit comments

Comments
 (0)