axiom-go

README

Axiom Go

---

Introduction

Axiom Go is a Go client library for accessing the Axiom API.

Currently, Axiom Go requires Go 1.17 or greater.

Installation

Install using go get

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

Install from source

git clone https://github.com/axiomhq/axiom-go.git
cd axiom-go
make # Run code generators, linters, sanitizers and test suits

Authentication

The client is initialized with an access token. The access token can be an API token retrieved from the settings page of the Axiom deployment (Settings -> API Tokens) or a personal token retrieved from the users profile page (Settings -> Profile).

When using Axiom Cloud the users organization ID must be provided in case a personal token is used. It can be retrieved from the address bar of the web browser when visiting Axiom Cloud and copying the identifier after the Axiom Cloud url. The organization ID can be omitted in case an API token is used.

When using Axiom Selfhost the URL of the deployment must be provided.

Access Token Types

The personal token grants access to all resources available to the user on their behalf.

The API token just allows ingestion or querying into or from the datasets the token is configured for.

Usage

Simple file ingestion with on the fly compression:

// Export `AXIOM_TOKEN` and `AXIOM_ORG_ID` (when using a personal token) for
// Axiom Cloud.
// Export `AXIOM_URL` and `AXIOM_TOKEN` for Axiom Selfhost.

// 1. Open the file to ingest.
f, err := os.Open("logs.json")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

// 2. Wrap it in a gzip enabled reader.
r, err := axiom.GzipEncoder(f)
if err != nil {
	log.Fatal(err)
}

// 3. Initialize the Axiom API client.
client, err := axiom.NewClient()
if err != nil {
	log.Fatal(err)
}

// 4. Ingest ⚡
// Note the JSON content type and Gzip content encoding being set because the
// client does not auto sense them.
res, err := client.Datasets.Ingest(context.Background(), dataset, r, axiom.JSON, axiom.Gzip, axiom.IngestOptions{})
if err != nil {
	log.Fatal(err)
}

// 5. Make sure everything went smoothly.
for _, fail := range res.Failures {
	log.Print(fail.Error)
}

For more sample code snippets, head over to the examples directory.

Documentation

• Visit the Go bindings documentation for the Axiom API on go.dev.

• Also get a detailed overview on Constants, Variables, Functions, and Types, and Source Files in the go.dev documentation.

---

You can find the Axiom and Axiom Go documentation on the docs website.

The documentation is divided into several sections:

• Axiom Cloud
• Getting Started
• Ingesting Data
• Analyzing Data
• Streaming Data
• Runing Axiom on Kubernetes
• Run Axiom on your Desktop
• Manage deployments with Axiom CLI
• Ingest using Elastic Beats
• Ingesting via Elasticsearch API
• Where to Get Support

Contributing

The main aim of this repository is to continue developing and advancing Axiom Go, making it faster and more simplified to use. Kindly check our contributing guide on how to propose bugfixes and improvements, and submitting pull requests to the project.

License

© Axiom, Inc., 2022

Distributed under MIT License (The MIT License).

See LICENSE for more information.