axiom

README

Axiom unlocks observability at any scale.

• Ingest with ease, store without limits: Axiom's next-generation datastore enables ingesting petabytes of data with ultimate efficiency. Ship logs from Kubernetes, AWS, Azure, Google Cloud, DigitalOcean, Nomad, and others.
• Query everything, all the time: Whether DevOps, SecOps, or EverythingOps, query all your data no matter its age. No provisioning, no moving data from cold/archive to "hot", and no worrying about slow queries. All your data, all. the. time.
• Powerful dashboards, for continuous observability: Build dashboards to collect related queries and present information that's quick and easy to digest for you and your team. Dashboards can be kept private or shared with others, and are the perfect way to bring together data from different sources.

For more information check out the official documentation and our community Discord.

Quickstart

Install using go get:

go get github.com/axiomhq/axiom-go/axiom

Import the package:

import "github.com/axiomhq/axiom-go/axiom"

If you use the Axiom CLI, run eval $(axiom config export -f) to configure your environment variables.

Otherwise create a personal token in the Axiom settings and export it as AXIOM_TOKEN. Set AXIOM_ORG_ID to the organization ID from the settings page of the organization you want to access.

[!NOTE] The organization ID is the slug below your organizations full name in the Axiom settings which resembles the full name. It has a copy button next to it. Alternatively you can just extract it from your browsers address bar when browsing the Axiom App: https://app.dev.axiomtestlabs.co/<your-org-id>/datasets.

You can also configure the client using options passed to the axiom.NewClient function:

client, err := axiom.NewClient(
    axiom.SetPersonalTokenConfig("AXIOM_TOKEN", "AXIOM_ORG_ID"),
)

[!NOTE] When only performing ingest or query operations, we recommend using an API token with minimal privileges, only! Create an API token with the appropriate scopes in the Axiom API tokens settings and export it as AXIOM_TOKEN.

Create and use a client like this:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/axiomhq/axiom-go/axiom"
    "github.com/axiomhq/axiom-go/axiom/ingest"
)

func main() {
    ctx := context.Background()

    client, err := axiom.NewClient()
    if err != nil {
        log.Fatalln(err)
    }
    
    if _, err = client.IngestEvents(ctx, "my-dataset", []axiom.Event{
        {ingest.TimestampField: time.Now(), "foo": "bar"},
        {ingest.TimestampField: time.Now(), "bar": "foo"},
    }); err != nil {
        log.Fatalln(err)
    }

    res, err := client.Query(ctx, "['my-dataset'] | where foo == 'bar' | limit 100")
    if err != nil {
        log.Fatalln(err)
    }
    for _, match := range res.Matches {
        fmt.Println(match.Data)
    }
}

For further examples, head over to the examples directory.

If you want to use a logging package, check if there is already an adapter in the adapters directory. We happily accept contributions for new adapters.

License

Distributed under the MIT License.

Documentation

Overview

Package axiom implements Go bindings for the Axiom API.

Usage:

import "github.com/axiomhq/axiom-go/axiom"
import "github.com/axiomhq/axiom-go/axiom/ingest" // When ingesting data
import "github.com/axiomhq/axiom-go/axiom/otel" // When using OpenTelemetry
import "github.com/axiomhq/axiom-go/axiom/query" // When constructing APL queries
import "github.com/axiomhq/axiom-go/axiom/querylegacy" // When constructing legacy queries

Construct a new Axiom client, then use the various services on the client to access different parts of the Axiom API. The package automatically takes its configuration from the environment if not specified otherwise. Refer to axiom.NewClient for details. The token can be an API or personal token. The API token however, will just allow ingestion or querying into or from the datasets the token is valid for, depending on its assigned permissions.

To construct a client:

client, err := axiom.NewClient()

or with axiom.Option functions:

client, err := axiom.NewClient(
    axiom.SetToken("..."),
    axiom.SetOrganizationID("..."),
)

Get the current authenticated user:

user, err := client.Users.Current(ctx)

NOTE: Every client method mapping to an API method takes a context.Context as its first parameter to pass cancellation signals and deadlines to requests. In case there is no context available, then context.Background can be used as a starting point.

For more code samples, check out the examples.