diff --git a/README.md b/README.md index f25dca85..76f66fd0 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,7 @@ others, and are the perfect way to bring together data from different sources. For more information check out the [official documentation](https://axiom.co/docs) -and our -[community Slack](https://axiomfm.slack.com/join/shared_invite/zt-w7d1vepe-L0upiOL6n6MXfjr33sCBUQ). +and our [community Slack](https://axiomfm.slack.com/join/shared_invite/zt-w7d1vepe-L0upiOL6n6MXfjr33sCBUQ). ## Quickstart @@ -45,14 +44,12 @@ import "github.com/axiomhq/axiom-go/axiom" If you use the [Axiom CLI](https://github.com/axiomhq/cli), run `eval $(axiom config export -f)` to configure your environment variables. -Otherwise create a personal token in -[the Axiom settings](https://app.axiom.co/profile) 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. +Otherwise create a personal token in [the Axiom settings](https://app.axiom.co/profile) +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. -You can also configure the client using -[options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) passed to -the `axiom.NewClient` function: +You can also configure the client using [options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) +passed to the `axiom.NewClient` function: ```go client, err := axiom.NewClient( @@ -63,6 +60,8 @@ client, err := axiom.NewClient( Create and use a client like this: ```go +package main + import ( "context" "fmt" @@ -99,6 +98,10 @@ func main() { For further examples, head over to the [examples](examples) directory. +If you want to use a logging package, check if there is already an adapter in +the [adapters](adapters) directory. We happily accept contributions for new +adapters. + ## License Distributed under the [MIT License](LICENSE). diff --git a/adapters/apex/README.md b/adapters/apex/README.md new file mode 100644 index 00000000..6488e073 --- /dev/null +++ b/adapters/apex/README.md @@ -0,0 +1,50 @@ +# Axiom Go Adapter for apex/log + +Adapter to ship logs generated by [apex/log](https://github.com/apex/log) to +Axiom. + +## Quickstart + +Follow the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +to install the Axiom Go package and configure your environment. + +Import the package: + +```go +// Imported as "adapter" to not conflict with the "apex/log" package. +import adapter "github.com/axiomhq/axiom-go/adapters/apex" +``` + +You can also configure the adapter using [options](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/apex#Option) +passed to the [New](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/apex#New) +function: + +```go +handler, err := adapter.New( + SetDataset("AXIOM_DATASET"), +) +``` + +To configure the underlying client manually either pass in a client that was +created according to the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +using [SetClient](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/apex#SetClient) +or pass [client options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) +to the adapter using [SetClientOptions](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/apex#SetClientOptions). + +```go +import adapter "github.com/axiomhq/axiom-go/axiom" + +// ... + +handler, err := adapter.New( + SetClientOptions( + axiom.SetPersonalTokenConfig("AXIOM_TOKEN", "AXIOM_ORG_ID"), + ), +) +``` + +### ❗ Important ❗ + +The adapter uses a buffer to batch events before sending them to Axiom. This +buffer must be flushed explicitly by calling [Close](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/apex#Handler.Close). +Checkout out the [example](../../examples/apex/main.go). diff --git a/adapters/logrus/README.md b/adapters/logrus/README.md new file mode 100644 index 00000000..291ba44a --- /dev/null +++ b/adapters/logrus/README.md @@ -0,0 +1,50 @@ +# Axiom Go Adapter for sirupsen/logrus + +Adapter to ship logs generated by [sirupsen/logrus](https://github.com/sirupsen/logrus) +to Axiom. + +## Quickstart + +Follow the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +to install the Axiom Go package and configure your environment. + +Import the package: + +```go +// Imported as "adapter" to not conflict with the "sirupsen/logrus" package. +import adapter "github.com/axiomhq/axiom-go/adapters/logrus" +``` + +You can also configure the adapter using [options](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/logrus#Option) +passed to the [New](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/logrus#New) +function: + +```go +hook, err := adapter.New( + SetDataset("AXIOM_DATASET"), +) +``` + +To configure the underlying client manually either pass in a client that was +created according to the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +using [SetClient](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/logrus#SetClient) +or pass [client options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) +to the adapter using [SetClientOptions](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/logrus#SetClientOptions). + +```go +import adapter "github.com/axiomhq/axiom-go/axiom" + +// ... + +hook, err := adapter.New( + SetClientOptions( + axiom.SetPersonalTokenConfig("AXIOM_TOKEN", "AXIOM_ORG_ID"), + ), +) +``` + +### ❗ Important ❗ + +The adapter uses a buffer to batch events before sending them to Axiom. This +buffer must be flushed explicitly by calling [Close](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/logrus#Hook.Close). +Checkout out the [example](../../examples/logrus/main.go). diff --git a/adapters/zap/README.md b/adapters/zap/README.md new file mode 100644 index 00000000..7cf029f8 --- /dev/null +++ b/adapters/zap/README.md @@ -0,0 +1,51 @@ +# Axiom Go Adapter for uber-go/zap + +Adapter to ship logs generated by [uber-go/zap](https://github.com/uber-go/zap) +to Axiom. + +## Quickstart + +Follow the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +to install the Axiom Go package and configure your environment. + +Import the package: + +```go +// Imported as "adapter" to not conflict with the "uber-go/zap" package. +import adapter "github.com/axiomhq/axiom-go/adapters/zap" +``` + +You can also configure the adapter using [options](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/zap#Option) +passed to the [New](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/zap#New) +function: + +```go +core, err := adapter.New( + SetDataset("AXIOM_DATASET"), +) +``` + +To configure the underlying client manually either pass in a client that was +created according to the [Axiom Go Quickstart](https://github.com/axiomhq/axiom-go#quickstart) +using [SetClient](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/zap#SetClient) +or pass [client options](https://pkg.go.dev/github.com/axiomhq/axiom-go/axiom#Option) +to the adapter using [SetClientOptions](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/zap#SetClientOptions). + +```go +import adapter "github.com/axiomhq/axiom-go/axiom" + +// ... + +core, err := adapter.New( + SetClientOptions( + axiom.SetPersonalTokenConfig("AXIOM_TOKEN", "AXIOM_ORG_ID"), + ), +) +``` + +### ❗ Important ❗ + +The adapter uses a buffer to batch events before sending them to Axiom. This +buffer must be flushed explicitly by calling [Sync](https://pkg.go.dev/github.com/axiomhq/axiom-go/adapters/zap#WriteSyncer.Sync). Refer to the +[zap documentation](https://pkg.go.dev/go.uber.org/zap/zapcore#WriteSyncer) +for details and checkout out the [example](../../examples/zap/main.go). diff --git a/examples/apex/main.go b/examples/apex/main.go index 806729ae..6126d3f5 100644 --- a/examples/apex/main.go +++ b/examples/apex/main.go @@ -17,6 +17,9 @@ func main() { } // 2. Have all logs flushed before the application exits. + // + // ❗THIS IS IMPORTANT❗ Without it, the logs will not be sent to Axiom as + // the buffer will not be flushed when the application exits. defer handler.Close() // 3. Set the Axiom handler as handler for apex. diff --git a/examples/logrus/main.go b/examples/logrus/main.go index 55d57b34..9db9c409 100644 --- a/examples/logrus/main.go +++ b/examples/logrus/main.go @@ -35,5 +35,8 @@ func main() { // 6. This makes sure logrus calls the registered exit handler. Alternaively // hook.Close() can be called manually. It is safe to call multiple times. + // + // ❗THIS IS IMPORTANT❗ Without it, the logs will not be sent to Axiom as + // the buffer will not be flushed when the application exits. logrus.Exit(0) } diff --git a/examples/zap/main.go b/examples/zap/main.go index ce0c136f..260106d7 100644 --- a/examples/zap/main.go +++ b/examples/zap/main.go @@ -22,6 +22,9 @@ func main() { logger := zap.New(core) // 3. Have all logs flushed before the application exits. + // + // ❗THIS IS IMPORTANT❗ Without it, the logs will not be sent to Axiom as + // the buffer will not be flushed when the application exits. defer func() { if syncErr := logger.Sync(); syncErr != nil { log.Fatal(syncErr)