Merge branch 'master' into python_quick

content/guides/integrations/sql/go_sql.md → codelabs/gosqlguide.md

@@ -1,34 +1,46 @@
----
-title: "Go"
-date: 2018-08-22T03:11:37-07:00
-draft: false
-aliases: [/integrations/sql/go]
-logo: /img/sql-gopher.png
----
-
-- [Introduction](#Introduction)
-- [Installing it](#installing-it)
-- [Using it](#using-it)
-  - [By registration](#by-registration)
-  - [By wrapping](#by-explicitly-wrapping-your-driver)
-- [Enabling OpenCensus](#enabling-opencensus)
-- [End to end example](#end-to-end-example)
-- [Examining the traces](#examining-the-traces)
-- [References](#references)
-
-## Introduction
+author:            Emmanuel Odeke and Prakriti Bansal
+summary:           Go SQL Integration Guide
+environments:      Web
+id:                gosqlguide
+
+# GoSQL Integration Guide
+
+## Overview of the tutorial
+Duration: 0:10
+
 We have a Go "database/sql" package/wrapper that is trace instrumented with OpenCensus!
 
-## Installing it
-To install the "database/sql" plugin, please run
+### Objectives:
+By the end of this tutorial, we will be able to achieve the following:
+* Use ocsql driver with sqlite3 applications
+* Export traces to backend (Jaeger in this case)
+
+### Requirements:
+* Go
+* Jaeger for trace exporting
+* sqlite3 [Install sqlite3](https://sqlite.org/index.html)
+
+Positive
+: For assistance setting up Jaeger, [Click here](/codelabs/jaeger) for a guided codelab.
+
+## Installing ocsql
+Duration: 0:09
+
+To install the "database/sql" plugin, please run:
 ```shell
-go get -u -v github.com/basvanbeek/ocsql
+go get -u -v contrib.go.opencensus.io/integrations/ocsql
 ```
 
-## Using it
-Given this simple initialization of a database/sql instance in Go:
+## Getting started 
+Duration: 0:08
 
-{{<highlight go>}}
+We will first create a `go-gettable` directory and a file `main.go`, like so:
+```shell
+mkdir -p ocsql-e2e && cd ocsql-e2e
+touch main.go
+```
+The following code gives a simple initialization of a database/sql instance in Go. 
+```go
 package main
 
 import (
@@ -38,28 +50,31 @@ import (
 
 func main() {
 	var ordinaryDriverName string // For example "mysql", "sqlite3" etc.
-	db, err := sql.Open(ordinaryDriverName, "resource.db")
+
+	db, err := sql.Open(driverName, "resource.db")
 	if err != nil {
 		log.Fatalf("Failed to open the SQL database: %v", err)
 	}
 	defer db.Close()
 }
-{{</highlight>}}
+```
+
+## Using ocsql
+Duration: 0:06
 
 We can use the OpenCensus trace-instrumented SQL driver wrapper in one of these two ways:
 
 ### By registration
-This mimicks the idiomatic recommendation to use the "database/sql" package in Go where
-we pass an implicitly registered driver to `sql.Open` which returns a [\*sql.DB handle](https://golang.org/pkg/database/sql/#DB)
+This mimicks the idiomatic recommendation to use the "database/sql" package in Go where we pass an implicitly registered driver to `sql.Open` which returns a [\*sql.DB handle](https://golang.org/pkg/database/sql/#DB)
 
-{{<highlight go>}}
+```go
 package main
 
 import (
 	"database/sql"
 	"log"
 
-	"github.com/basvanbeek/ocsql"
+	"contrib.go.opencensus.io/integrations/ocsql"
 )
 
 func main() {
@@ -76,39 +91,57 @@ func main() {
 	}
 	defer db.Close()
 }
-{{</highlight>}}
+```
 
 ### By explicitly wrapping your driver
-This option is useful if you'd like to be more explicit and if your database package exports
-its driver implementation.
+This option is useful if you'd like to be more explicit and if your database package exports its driver implementation.
 
-{{<highlight go>}}
+```go
 package main
 
-import "github.com/basvanbeek/ocsql"
+import "contrib.go.opencensus.io/integrations/ocsql"
 
 func main() {
 	db := ocsql.Wrap(&theDBObjectInstance{}, ocsql.WithAllTraceOptions())
 	_ = db
 }
-{{</highlight>}}
+```
 
 ## Enabling OpenCensus
-To examine the traces, we need to hook up our favorite Go exporter as per the [Go exporters guides](/guides/exporters/supported-exporters/go/)
+Duration: 0:05
 
-## End to end example
-And now to examine the exported traces, let's make a simple name registry app.
-For simplicitly, we use a sqlite3 database. To examine our traces, we'll use Jaeger.
-{{% notice tip %}}
-For assistance setting up Jaeger, [Click here](/codelabs/jaeger) for a guided codelab.
-{{% /notice %}}
+To enable observability with OpenCensus, we need to hook up our favorite Go exporter as per the [Go exporters guides](/guides/exporters/supported-exporters/go/).
+This can be achieved like so (with Jaeger in this case):
 
-Please place the code below inside a `go-gettable` directory and a file `main.go`, so
-```shell
-mkdir -p ocsql-e2e && touch main.go
+```go
+import (
+	"go.opencensus.io/exporter/jaeger"
+	"go.opencensus.io/trace"
+)
+func enableOpenCensusTracingAndExporting() error {
+	// For demo purposes, we'll always trace
+	trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})
+
+	je, err := jaeger.NewExporter(jaeger.Options{
+		AgentEndpoint: "localhost:6831",
+		Endpoint:      "http://localhost:14268",
+		ServiceName:   "ocsql-demo",
+	})
+	if err == nil {
+		// On success, register it as a trace exporter
+		trace.RegisterExporter(je)
+	}
+
+	return err
+}
 ```
 
-{{<highlight go>}}
+## End to end code
+Duration: 0:04
+
+And now to examine the exported traces, let's make a simple name registry app. For simplicitly, we use a sqlite3 database.
+Place the following code in `main.go`. Save and close the file.
+```go
 package main
 
 import (
@@ -117,7 +150,7 @@ import (
 	"log"
 	"time"
 
-	"github.com/basvanbeek/ocsql"
+	"contrib.go.opencensus.io/integrations/ocsql"
 	"go.opencensus.io/exporter/jaeger"
 	"go.opencensus.io/trace"
 
@@ -211,19 +244,20 @@ func enableOpenCensusTracingAndExporting() error {
 
 	return err
 }
-{{</highlight>}}
+```
 
-## Examine the traces
-On visiting http://localhost:16686/ we can see something similar to below:
+With the code above properly placed in `main.go`, we can now run:
+```shell
+go run main.go
+```
 
-![Traces list](/img/ocsql-all-traces.png)
+## Examining the traces 
+Duration: 0:03
+
+On visiting http://localhost:16686/ we can see something similar to below:
 
-and on clicking to get details about the most recent trace
+![Traces list](./gosqlguide/img/ocsql-all-traces.png)
 
-![Detailed trace](/img/ocsql-detailed-trace.png)
+On clicking to get details about the most recent trace:
 
-## References
-Reference|URL
----|---
-GoDoc|[github.com/basvanbeek/ocsql](https://godoc.org/github.com/basvanbeek/ocsql)
-Medium blogpost|[OpenCensus and Go database/sql by Bas van Beek](https://medium.com/@bas.vanbeek/opencensus-and-go-database-sql-322a26be5cc5)
+![Detailed trace](./gosqlguide/img/ocsql-detailed-trace.png)

codelabs/gosqlguide/codelab.json

@@ -0,0 +1,20 @@
+{
+  "environment": "web",
+  "source": "gosqlguide.md",
+  "format": "html",
+  "prefix": "../../",
+  "mainga": "UA-49880327-14",
+  "updated": "2019-01-15T01:46:06+05:30",
+  "id": "gosqlguide",
+  "duration": 7,
+  "title": "GoSQL Integration Guide",
+  "author": "Emmanuel Odeke and Prakriti Bansal",
+  "summary": "Go SQL Integration Guide",
+  "theme": "",
+  "status": null,
+  "category": null,
+  "tags": [
+    "web"
+  ],
+  "url": "gosqlguide"
+}