doc(adapters): add sub-package readme files

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).

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).

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).

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).

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.

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)
 }

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)