add Dockerfile and docker-compose.yml to run example code (#635)

* add optional server url arg to http client example

Signed-off-by: Andrew Hsu <[email protected]>

* add Dockerfile to build example http images

Multi-stage Dockerfile with targets for building example http server and
client.

  $ docker build --tag the-server --target example-http-server .
  $ docker build --tag the-client --target example-http-client .

Signed-off-by: Andrew Hsu <[email protected]>

* add docker-compose.yml file for running examples

This docker compose configuration file will help a new user to compile
and run the example code quickly. Uses the Dockerfile to build images
with compiled examples.

  $ docker-compose build http-server http-client
  $ docker-compose up http-server http-client

Signed-off-by: Andrew Hsu <[email protected]>

* add newline to last message of example http client

Signed-off-by: Andrew Hsu <[email protected]>

* add optional collector url arg to zipkin client example

Signed-off-by: Andrew Hsu <[email protected]>

* add Dockerfile target to build zipkin client

For building the example zipkin client:

  $ docker build --tag zipkin-client --target example-zipkin-client .

Signed-off-by: Andrew Hsu <[email protected]>

* add docker compose service to run zipkin examples

Services to run the zipkin client along with a zipkin collector:

  $ docker-compose build zipkin-client
  $ docker-compose up zipkin-collector zipkin-client

Since the zipkin collector takes a few seconds before it is ready to
receive traces, I added a simple retry loop to the client command.

The collector service exposes port 9411 so user can visit
http//localhost:9411/ to see the trace sent to the collector. Be sure to
search by the trace id logged by the client.

Signed-off-by: Andrew Hsu <[email protected]>

* Update Dockerfile with AL2 declaration

As described in https://www.apache.org/licenses/LICENSE-2.0#apply

Co-Authored-By: Tyler Yahn <[email protected]>

* Update docker-compose.yml with AL2 declaration

As described in https://www.apache.org/licenses/LICENSE-2.0#apply

Co-Authored-By: Tyler Yahn <[email protected]>

* pass server url as flag in example http client

  $ ./client -h
  Usage of ./client:
    -server string
          server url (default "http://localhost:7777/hello")

Signed-off-by: Andrew Hsu <[email protected]>

* pass zipkin url as flag in example zipkin client

  $ ./zipkin -h
  Usage of ./zipkin:
    -zipkin string
          zipkin url (default "http://localhost:9411/api/v2/spans")

Signed-off-by: Andrew Hsu <[email protected]>

* move Dockerfile and docker-compose.yml into example dir

Signed-off-by: Andrew Hsu <[email protected]>

* add Dockerfile and docker-compose.yml for zipkin example

Signed-off-by: Andrew Hsu <[email protected]>

* update zipkin example README.md

With instructions on how to use docker-compose to run the example.

Signed-off-by: Andrew Hsu <[email protected]>

* add http example README.md

With instructions on how to use docker-compose to run the example.

Signed-off-by: Andrew Hsu <[email protected]>

* Update example/http/Dockerfile WORKDIR

Co-Authored-By: Krzesimir Nowak <[email protected]>

* Update example/http/Dockerfile RUN go install

Co-Authored-By: Krzesimir Nowak <[email protected]>

* Update example/http/Dockerfile RUN go install

Co-Authored-By: Krzesimir Nowak <[email protected]>

* Update example/zipkin/Dockerfile WORKDIR

Co-Authored-By: Krzesimir Nowak <[email protected]>

* Update example/zipkin/Dockerfile RUN go install

Co-Authored-By: Krzesimir Nowak <[email protected]>

Co-authored-by: Tyler Yahn <[email protected]>
Co-authored-by: Krzesimir Nowak <[email protected]>
Co-authored-by: Joshua MacDonald <[email protected]>

example/http/Dockerfile

@@ -0,0 +1,24 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+FROM golang:alpine AS base
+COPY . /go/src/github.com/open-telemetry/opentelemetry-go/
+WORKDIR /go/src/github.com/open-telemetry/opentelemetry-go/example/http/
+
+FROM base AS example-http-server
+RUN go install ./server/server.go
+CMD ["/go/bin/server"]
+
+FROM base AS example-http-client
+RUN go install ./client/client.go
+CMD ["/go/bin/client"]

example/http/README.md

@@ -0,0 +1,24 @@
+# HTTP Client-Server Example
+
+An HTTP client connects to an HTTP server. They both generate span information to `stdout`.
+These instructions expect you have [docker-compose](https://docs.docker.com/compose/) installed.
+
+Bring up the `http-server` and `http-client` services to run the example:
+```sh
+docker-compose up --detach http-server http-client
+```
+
+The `http-client` service sends just one HTTP request to `http-server` and then exits. View the span generated to `stdout` in the logs:
+```sh
+docker-compose logs http-client
+```
+
+View the span generated by `http-server` in the logs:
+```sh
+docker-compose logs http-server
+```
+
+Shut down the services when you are finished with the example:
+```sh
+docker-compose down
+```

example/http/client/client.go

@@ -16,6 +16,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"fmt"
 	"io/ioutil"
 	"log"
@@ -51,6 +52,8 @@ func initTracer() {
 
 func main() {
 	initTracer()
+	url := flag.String("server", "http://localhost:7777/hello", "server url")
+	flag.Parse()
 
 	client := http.DefaultClient
 	ctx := correlation.NewContext(context.Background(),
@@ -62,7 +65,7 @@ func main() {
 	tr := global.Tracer("example/client")
 	err := tr.WithSpan(ctx, "say hello",
 		func(ctx context.Context) error {
-			req, _ := http.NewRequest("GET", "http://localhost:7777/hello", nil)
+			req, _ := http.NewRequest("GET", *url, nil)
 
 			ctx, req = httptrace.W3C(ctx, req)
 			httptrace.Inject(ctx, req)
@@ -85,5 +88,5 @@ func main() {
 	fmt.Printf("Response Received: %s\n\n\n", body)
 	fmt.Printf("Waiting for few seconds to export spans ...\n\n")
 	time.Sleep(10 * time.Second)
-	fmt.Printf("Inspect traces on stdout")
+	fmt.Printf("Inspect traces on stdout\n")
 }

example/http/docker-compose.yml

@@ -0,0 +1,34 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+version: "3.7"
+services:
+  http-server:
+    build:
+      dockerfile: $PWD/Dockerfile
+      context: ../..
+      target: example-http-server
+    networks:
+      - example
+  http-client:
+    build:
+      dockerfile: $PWD/Dockerfile
+      context: ../..
+      target: example-http-client
+    command: ["/go/bin/client", "-server", "http://http-server:7777/hello"]
+    networks:
+      - example
+    depends_on:
+      - http-server
+networks:
+  example:

example/zipkin/Dockerfile

@@ -0,0 +1,18 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+FROM golang:alpine
+COPY . /go/src/github.com/open-telemetry/opentelemetry-go/
+WORKDIR /go/src/github.com/open-telemetry/opentelemetry-go/example/zipkin/
+RUN go install ./main.go
+CMD ["/go/bin/main"]

example/zipkin/README.md

@@ -1,16 +1,22 @@
 # Zipkin Exporter Example
 
-Sends spans to zipkin collector.
+Send an example span to a [Zipkin](https://zipkin.io/) service.
+These instructions expect you have [docker-compose](https://docs.docker.com/compose/) installed.
 
-### Run collector
+Bring up the `zipkin-collector` service and example `zipkin-client` service to send an example trace:
+```sh
+docker-compose up --detach zipkin-collector zipkin-client
+```
 
+The `zipkin-client` service sends just one trace and exits. Retrieve the `traceId` generated by the `zipkin-client` service; should be the last line in the logs:
 ```sh
-docker run -d -p 9411:9411 openzipkin/zipkin
+docker-compose logs --tail=1 zipkin-client
 ```
 
-### Run client
+With the `traceId` you can view the trace from the `zipkin-collector` service UI hosted on port `9411`, e.g. with `traceId` of `f5695ba3b2ed00ea583fa4fa0badbeef`:
+http://localhost:9411/zipkin/traces/f5695ba3b2ed00ea583fa4fa0badbeef
 
+Shut down the services when you are finished with the example:
 ```sh
-go build .
-./zipkin
+docker-compose down
 ```

example/zipkin/docker-compose.yml

@@ -0,0 +1,35 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+version: "3.7"
+services:
+  zipkin-collector:
+    image: openzipkin/zipkin-slim:latest
+    ports:
+      - "9411:9411"
+    networks:
+      - example
+  zipkin-client:
+    build:
+      dockerfile: $PWD/Dockerfile
+      context: ../..
+    command:
+      - "/bin/sh"
+      - "-c"
+      - "while ! nc -w 1 -z zipkin-collector 9411; do echo sleep for 1s waiting for zipkin-collector to become available; sleep 1; done && /go/bin/main -zipkin http://zipkin-collector:9411/api/v2/spans"
+    networks:
+      - example
+    depends_on:
+      - zipkin-collector
+networks:
+  example:

example/zipkin/main.go

@@ -18,6 +18,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"log"
 	"os"
 	"time"
@@ -31,10 +32,10 @@ import (
 var logger = log.New(os.Stderr, "zipkin-example", log.Ldate|log.Ltime|log.Llongfile)
 
 // initTracer creates a new trace provider instance and registers it as global trace provider.
-func initTracer() {
+func initTracer(url string) {
 	// Create Zipkin Exporter
 	exporter, err := zipkin.NewExporter(
-		"http://localhost:9411/api/v2/spans",
+		url,
 		"zipkin-example",
 		zipkin.WithLogger(logger),
 	)
@@ -59,7 +60,10 @@ func initTracer() {
 }
 
 func main() {
-	initTracer()
+	url := flag.String("zipkin", "http://localhost:9411/api/v2/spans", "zipkin url")
+	flag.Parse()
+
+	initTracer(*url)
 
 	ctx := context.Background()