Merge pull request #4 from stoewer/build-system-and-docker

Basic build system using make and Docker

Author: mapno

.dockerignore

@@ -0,0 +1,3 @@
+/examples
+*.md
+Dockerfile

Dockerfile

@@ -0,0 +1,23 @@
+FROM golang:alpine AS xk6-client-tracing-build
+
+RUN apk add --no-cache \
+    build-base \
+    gcc \
+    git \
+    make
+
+RUN go install go.k6.io/xk6/cmd/xk6@latest \
+    && wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s v1.50.0 \
+    && golangci-lint --version
+
+WORKDIR /opt/xk6-client-tracing
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+RUN make build
+
+FROM alpine:latest
+
+COPY --from=xk6-client-tracing-build /opt/xk6-client-tracing/k6-tracing /k6-tracing
+ENTRYPOINT [ "/k6-tracing" ]

Makefile

@@ -0,0 +1,29 @@
+BINARY     ?= k6-tracing
+IMAGE      ?= grafana/xk6-client-tracing
+IMAGE_TAG  ?= latest
+
+GO_MODULE      := $(shell head -n1 go.mod | cut -d' ' -f2)
+GO_TEST_OPTS   := -race -count=1 -cover
+GO_LINT_OPTS   := --config ./golangci.yml
+XK6_BUILD_OPTS := --output ./$(BINARY)
+
+.PHONY: build
+build:
+	xk6 build $(XK6_BUILD_OPTS) --with $(GO_MODULE)=.
+
+.PHONY: test
+test:
+	go test $(GO_TEST_OPTS) ./...
+
+.PHONY: lint
+lint:
+	golangci-lint run $(GO_LINT_OPTS) ./...
+
+.PHONY: docker
+docker:
+	docker build . -t $(IMAGE):$(IMAGE_TAG)
+
+.PHONY: clean
+clean:
+	go clean -cache -testcache
+	docker rmi -f $(IMAGE)

README.md

@@ -6,55 +6,105 @@
 
 This extension provides k6 with the required functionality required to load test distributed tracing backends.
 
-## Getting started  
+## Getting started
 
-To start using k6 with the extension, ensure you have the prerequisites:
+To start using the k6 tracing extension, ensure you have the following prerequisites installed:
+
+- Docker
+- docker-compose
+- make
+
+### Build docker image
+
+The docker image is compiled using a multi-stage Docker build and does not require further dependencies. 
+To start the build process run:
+
+```shell
+make docker
+```
+
+After the command completed successfully the image `grafana/xk6-client-tracing:latest` is available.
+
+### Run docker-compose example
+
+> Note: before running the docker-compose example, make sure to complete the docker image build step above!
+
+To run the example `cd` into the directory `examples/basic` and run:
+
+```shell
+docker-compose up -d
+```
+
+In the example `k6-tracing` uses the script `basic.js` to generate spans and sends them to the `otel-collector`.
+The generated spans can be observed by inspecting the collector's logs:
+
+```shell
+docker-compose logs -f otel-collector
+```
+
+The example uses the OTLP gRPC exporter. 
+If you want to use Jaeger gRPC, you can change `basic.js` and use the following settings:
+
+```javascript
+const client = new tracing.Client({
+    endpoint: "otel-collector:14250",
+    exporter: "jaeger",
+    insecure: true,
+});
+```
+
+> Note: HTTP exporters aren't supported (yet)
+
+### Build locally
+
+Building the extension locally has additional prerequisites:
 
 - [Go toolchain](https://go101.org/article/go-toolchain.html)
 - Git
 
-Then:
+Furthermore, the build also requires [`xk6`](https://github.com/grafana/xk6) to compile k6 with the bundled tracing extension.
+Run the following command to install `xk6`:
 
-1. Install `xk6`:
 ```shell
 go install go.k6.io/xk6/cmd/xk6@latest
 ```
 
-2. Build the binary:
+To build binary run:
 ```shell
-xk6 build --with github.com/grafana/xk6-client-tracing@latest
+make build
+```
+
+The build step produces the `k6-tracing` binary.
+To test the binary you first need to change the endpoint in the client configuration in `examples/basic/basic.js`:
+
+```javascript
+const client = new tracing.Client({
+    endpoint: "localhost:4317",
+    exporter: "otlp",
+    insecure: true,
+});
 ```
 
-Once you've your new binary ready, you can run a local OTEL collector:
+Once you've your new binary and configuration ready, you can run a local OTEL collector:
 ```bash
 docker run --rm -p 13133:13133 -p 14250:14250 -p 14268:14268 \
       -p 55678-55679:55678-55679 -p 4317:4317 -p 9411:9411 \
-      -v "${PWD}/collector-config.yaml":/collector-config.yaml \
+      -v "${PWD}/examples/shared/collector-config.yaml":/collector-config.yaml \
       --name otelcol otel/opentelemetry-collector \
       --config collector-config.yaml
 ```
 
 Once that's done, you can run a test like:
 ```
-./k6 run examples/basic.js
+./k6-tracing run examples/basic/basic.js
 ```
 
-And see your spans on the OTEL collector logs!
-
-The example uses the OTLP gRPC exporter. If you want to use Jaeger gRPC, you can use these settings:
-```javascript
-const client = new tracing.Client({
-    endpoint: "0.0.0.0:14250",
-    exporter: "jaeger",
-    insecure: true,
-});
-```
-
-> Note: HTTP exporters aren't supported (yet)
+And see the generated spans in the OTEL collector logs!
 
 ## Using the extension with Grafana Cloud
 
 You can do that, by using the OTLP exporter and setting the required auth credentials:
+
 ```javascript
 const client = new tracing.Client({
     endpoint: "you-tempo-endpoint:443"
@@ -66,5 +116,3 @@ const client = new tracing.Client({
     }
 });
 ```
-
-

examples/basic.js examples/basic/basic.js

@@ -17,7 +17,7 @@ const traceIDs = new SharedArray('traceIDs', function () {
 });
 
 const client = new tracing.Client({
-    endpoint: "0.0.0.0:4317",
+    endpoint: "otel-collector:4317",
     exporter: "otlp",
     insecure: true,
 });

examples/basic/docker-compose.yml

@@ -0,0 +1,26 @@
+version: "3"
+
+services:
+  k6-tracing:
+    image: grafana/xk6-client-tracing:latest
+    command:
+      - run
+      - /basic.js
+    volumes:
+      - ./basic.js:/basic.js:ro
+    depends_on:
+      - otel-collector
+
+  otel-collector:
+    image: otel/opentelemetry-collector:latest
+    command:
+      - --config=/collector-config.yaml
+    volumes:
+      - ../shared/collector-config.yaml:/collector-config.yaml:ro
+    ports:
+      - "13133:13133"
+      - "14250:14250"
+      - "14268:14268"
+      - "55678-55679:55678-55679"
+      - "4317:4317"
+      - "9411:9411"

collector-config.yaml examples/shared/collector-config.yaml

@@ -0,0 +1,26 @@
+run:
+  issues-exit-code: 1
+  tests: true
+
+linters:
+  enable:
+    - errcheck
+    - goconst
+    - gofmt
+    - goimports
+    - gosimple
+    - govet
+    - ineffassign
+    - megacheck
+    - misspell
+    - revive
+    - typecheck
+    - unconvert
+    - unparam
+    - unused
+
+linter-settings:
+
+issues:
+  exclude:
+    - "var-naming: don't use an underscore in package name"

golangci.yml

@@ -44,11 +44,11 @@ func (r *tracingClientModule) NewModuleInstance(vu modules.VU) modules.Instance
 	return &ClientTracing{vu: vu}
 }
 
-func (r *ClientTracing) Exports() modules.Exports {
+func (ct *ClientTracing) Exports() modules.Exports {
 	return modules.Exports{
 		Named: map[string]interface{}{
-			"Client":                r.xclient,
-			"generateRandomTraceID": r.generateRandomTraceID,
+			"Client":                ct.xclient,
+			"generateRandomTraceID": ct.generateRandomTraceID,
 		},
 	}
 }
@@ -80,9 +80,9 @@ type Config struct {
 	Headers map[string]string `json:"headers"`
 }
 
-func (c *ClientTracing) xclient(g goja.ConstructorCall) *goja.Object {
+func (ct *ClientTracing) xclient(g goja.ConstructorCall) *goja.Object {
 	var cfg Config
-	rt := c.vu.Runtime()
+	rt := ct.vu.Runtime()
 	err := rt.ExportTo(g.Argument(0), &cfg)
 	if err != nil {
 		common.Throw(rt, fmt.Errorf("Client constructor expects first argument to be Config"))
@@ -140,7 +140,7 @@ func (c *ClientTracing) xclient(g goja.ConstructorCall) *goja.Object {
 	if err != nil {
 		log.Fatal(err)
 	}
-	exporter.Start(context.Background(), componenttest.NewNopHost())
+	_ = exporter.Start(context.Background(), componenttest.NewNopHost())
 
 	if err != nil {
 		log.Fatal(fmt.Errorf("failed to create exporter: %v", err))
@@ -149,11 +149,11 @@ func (c *ClientTracing) xclient(g goja.ConstructorCall) *goja.Object {
 	return rt.ToValue(&Client{
 		exporter: exporter,
 		cfg:      &cfg,
-		vu:       c.vu,
+		vu:       ct.vu,
 	}).ToObject(rt)
 }
 
-func (c *ClientTracing) generateRandomTraceID() string {
+func (ct *ClientTracing) generateRandomTraceID() string {
 	bytes := make([]byte, 16)
 	if _, err := rand.Read(bytes); err != nil {
 		return ""