examples: out_multiinstance: update out_multiinstnace example

- Update README to explain multi-instance go plugin support
- Update the plugin code to print out the reords like out_gstdout
- Add Dockerfile that provides ability to build, run and visualize
multi-instance example.

Author: Warren Fernandes

examples/out_multiinstance/Dockerfile

@@ -0,0 +1,26 @@
+FROM golang:1.12 as gobuilder
+
+WORKDIR /root
+
+ENV GOOS=linux\
+    GOARCH=amd64
+
+COPY / /root/
+
+RUN go get github.com/fluent/fluent-bit-go/...
+
+RUN go build \
+    -buildmode=c-shared \
+    -o /out_multiinstance.so \
+    out.go
+
+FROM fluent/fluent-bit:1.1
+
+COPY --from=gobuilder /out_multiinstance.so /fluent-bit/bin/
+COPY --from=gobuilder /root/fluent-bit.conf /fluent-bit/etc/
+COPY --from=gobuilder /root/plugins.conf /fluent-bit/etc/
+
+EXPOSE 2020
+
+# CMD ["/fluent-bit/bin/fluent-bit", "--plugin", "/fluent-bit/bin/out_multiinstance.so", "--config", "/fluent-bit/etc/fluent-bit.conf"]¬
+CMD ["/fluent-bit/bin/fluent-bit", "--config", "/fluent-bit/etc/fluent-bit.conf"]¬

examples/out_multiinstance/README.md

@@ -1,3 +1,100 @@
-This example demonstrates using a plugin where there are multiple instances
-and `FLBPluginFlushCtx` is used to disambiguate multiple instances of the
-output plugin.
+# Example: out_multiinstance
+
+The following example code implements an output plugin that works with
+multiple configured instances. It describes how to share context from the
+specified instance configuration to the flush callback.
+
+Every output plugin go through four callbacks associated to different phases:
+
+| Plugin Phase        | Callback                   |
+|---------------------|----------------------------|
+| Registration        | FLBPluginRegister()        |
+| Initialization      | FLBPluginInit()            |
+| Runtime Flush       | FLBPluginFlushCtx()        |
+| Exit                | FLBPluginExit()            |
+
+## Plugin Registration
+
+When Fluent Bit loads a Golang plugin, it looks up and loads the registration
+callback that aims to populate the internal structure with plugin name and
+description:
+
+```go
+//export FLBPluginRegister
+func FLBPluginRegister(def unsafe.Pointer) int {
+	return output.FLBPluginRegister(ctx, "multiinstance", "Testing multiple instances")
+}
+```
+
+This function is invoked at start time _before_ any configuration is done
+inside the engine.
+
+## Plugin Initialization
+
+Before the engine starts, it initializes all plugins that were configured.
+As part of the initialization, the plugin can obtain configuration parameters
+and do any other internal checks. It can also set the context for this
+instance in case params need to be retrieved during flush.
+E.g:
+
+```go
+//export FLBPluginInit
+func FLBPluginInit(ctx unsafe.Pointer) int {
+	id := output.FLBPluginConfigKey(plugin, "id")
+	log.Printf("[multiinstance] id = %q", id)
+	// Set the context to point to any Go variable
+	output.FLBPluginSetContext(plugin, unsafe.Pointer(&id))
+	return output.FLB_OK
+}
+```
+
+The function must return FLB\_OK when it initialized properly or FLB\_ERROR if
+something went wrong. If the plugin reports an error, the engine will _not_
+load the instance.
+
+## Runtime Flush with Context
+
+Upon flush time, when Fluent Bit wants to flush it's buffers, the runtime flush
+callback will be triggered.
+
+The callback will receive the configuration context, a raw buffer of msgpack
+data, the proper bytes length and the associated tag.
+
+```go
+//export FLBPluginFlushCtx
+func FLBPluginFlush(ctx, data unsafe.Pointer, length C.int, tag *C.char) int {
+
+    id := *(*string)(ctx)
+	log.Printf("[multiinstance] Flush called for id: %s", *id)
+    return output.FLB_OK
+}
+```
+
+When done, there are three returning values available:
+
+| Return value  | Description                                    |
+|---------------|------------------------------------------------|
+| FLB\_OK       | The data have been processed normally.         |
+| FLB\_ERROR    | An internal error have ocurred, the plugin will not handle the set of records/data again. |
+| FLB\_RETRY    | A recoverable error have ocurred, the engine can try to flush the records/data later.|
+
+## Plugin Exit
+
+When Fluent Bit will stop using the instance of the plugin, it will trigger the exit callback. e.g:
+
+```go
+//export FLBPluginExit
+func FLBPluginExit() int {
+	return output.FLB_OK
+}
+```
+
+## Playground
+
+Build the docker image locally to see how it works.
+
+```bash
+$ cd $GOPATH/src/github.com/fluent/fluent-bit-go/examples/out_multiinstance
+$ docker build . -t fluent-bit-multiinstance
+$ docker run -it --rm fluent-bit-multiinstance
+```

examples/out_multiinstance/fluent-bit.conf

@@ -0,0 +1,28 @@
+[SERVICE]
+    Flush        5
+    Daemon       Off
+    Log_Level    info
+    Parsers_File parsers.conf
+    Plugins_File plugins.conf
+    HTTP_Server  Off
+    HTTP_Listen  0.0.0.0
+    HTTP_Port    2020
+
+[INPUT]
+    Name cpu
+    Tag  cpu.local
+    Interval_Sec 1
+
+[INPUT]
+    Name dummy
+    Tag  dummy.local
+
+[OUTPUT]
+    Name  multiinstance
+    Match cpu*
+    Id cpu_metrics
+
+[OUTPUT]
+    Name  multiinstance
+    Match dummy*
+    Id dummy_metrics

examples/out_multiinstance/out.go

@@ -1,7 +1,9 @@
+// +build example
 package main
 
 import (
 	"C"
+	"fmt"
 	"log"
 	"unsafe"
 
@@ -24,23 +26,34 @@ func FLBPluginInit(plugin unsafe.Pointer) int {
 
 //export FLBPluginFlush
 func FLBPluginFlush(data unsafe.Pointer, length C.int, tag *C.char) int {
-	log.Print("Flush called for unknown instance")
+	log.Print("[multiinstance] Flush called for unknown instance")
 	return output.FLB_OK
 }
 
 //export FLBPluginFlushCtx
 func FLBPluginFlushCtx(ctx, data unsafe.Pointer, length C.int, tag *C.char) int {
 	// Cast context back into the original type for the Go variable
-	id := (*string)(ctx)
-	log.Printf("Flush called for id: %s", *id)
+	id := *(*string)(ctx)
+	log.Printf("[multiinstance] Flush called for id: %s", id)
 
 	dec := output.NewDecoder(data, int(length))
 
+	count := 0
 	for {
-		ret, _, _ := output.GetRecord(dec)
+		ret, ts, record := output.GetRecord(dec)
 		if ret != 0 {
 			break
 		}
+
+		// Print record keys and values
+		timestamp := ts.(output.FLBTime)
+		fmt.Printf("[%d] %s: [%s, {", count, C.GoString(tag), timestamp.String())
+
+		for k, v := range record {
+			fmt.Printf("\"%s\": %v, ", k, v)
+		}
+		fmt.Printf("}\n")
+		count++
 	}
 
 	return output.FLB_OK

examples/out_multiinstance/plugins.conf

@@ -0,0 +1,2 @@
+[PLUGINS]
+  Path /fluent-bit/bin/out_multiinstance.so