From c8c0733f30f691a4a673df1229ccfe2ef523e441 Mon Sep 17 00:00:00 2001 From: Kapil Verma Date: Wed, 23 Nov 2022 17:34:30 +0530 Subject: [PATCH 1/2] updated docs --- go/core/README.md | 31 +++++++++---- go/database/sql/README.md | 40 +++++++++------- go/gorrila/mux/README.md | 96 +++++++++++++++++++++++++++++++++++++++ go/net/http/README.md | 68 +++++---------------------- 4 files changed, 154 insertions(+), 81 deletions(-) create mode 100644 go/gorrila/mux/README.md diff --git a/go/core/README.md b/go/core/README.md index 5406a38b..eaec9bad 100644 --- a/go/core/README.md +++ b/go/core/README.md @@ -12,19 +12,34 @@ This is a support package and will be installed indirectly by other go sqlcommen ### Configuration -Users are given control over what tags they want to append by using `core.CommenterOptions` struct. +Users are given control over what tags they want to append by using `core.CommenterConfig` struct. ```go -type CommenterOptions struct { +type CommenterConfig struct { EnableDBDriver bool - EnableTraceparent bool // OpenTelemetry trace information - EnableRoute bool // applicable for web frameworks - EnableFramework bool // applicable for web frameworks - EnableController bool // applicable for web frameworks - EnableAction bool // applicable for web frameworks + EnableRoute bool + EnableFramework bool + EnableController bool + EnableAction bool + EnableTraceparent bool EnableApplication bool - Application string // user-provided application-name. optional } ``` +Users can also set the values for some static tags by using `core.StaticTags` struct. + +```go +type StaticTags struct { + Application string + DriverName string +} +``` +These two structs together form the `core.CommenterOptions` struct, which is used by [sqlcommenter/go/database/sql](../database/sql/README.md). + +```go +type CommenterOptions struct { + Config CommenterConfig + Tags StaticTags +} +``` \ No newline at end of file diff --git a/go/database/sql/README.md b/go/database/sql/README.md index 1a3d71dc..9459083d 100644 --- a/go/database/sql/README.md +++ b/go/database/sql/README.md @@ -1,22 +1,12 @@ -# go-sql-driver [In development] +# go-sql-driver SQLcommenter is a plugin/middleware/wrapper to augment application related information/tags with SQL Statements that can be used later to correlate user code with SQL statements. ## Installation -### Install from source - -* Clone the source -* In terminal go inside the client folder location where we need to import sqlcommenter go-sql module and enter the below commands - ```shell -go mod edit -replace google.com/sqlcommenter=path/to/google/sqlcommenter/go-sql - -go mod tiny - -go get google.com/sqlcommenter/gosql +go get -u github.com/google/sqlcommenter/go/database/sql ``` -### Install from github [To be added] ## Usage @@ -24,7 +14,16 @@ Please use the sqlcommenter's default go-sql database driver to execute statemen Due to inherent nature of Go, the safer way to pass information from framework to database driver is via `context`. So, it is recommended to use the context based methods of `DB` interface like `QueryContext`, `ExecContext` and `PrepareContext`. ```go -db, err := gosql.Open("", "", sqlcommenter.CommenterOptions{:}) +import ( + gosql "github.com/google/sqlcommenter/go/database/sql" + sqlcommentercore "github.com/google/sqlcommenter/go/core" + _ "github.com/lib/pq" // or any other database driver +) + +db, err := gosql.Open("", "", sqlcommentercore.CommenterOptions{ + Config: sqlcommentercore.CommenterConfig{:bool} + Tags : sqlcommentercore.StaticTags{: string} // optional +}) ``` ### Configuration @@ -40,15 +39,24 @@ type CommenterOptions struct { EnableController bool // applicable for web frameworks EnableAction bool // applicable for web frameworks EnableApplication bool // applicable for web frameworks - Application string // user-provided application-name. optional - } +} +``` + +Users can also provide static tags they want to use by using `core.StaticTags` struct. These tags are optional + +```go +type StaticTags struct { + Application string + DriverName string +} ``` The driver will try to use the module-name from the project's `go.mod` as the application name if `EnableApplication` is `true` and no `Application` string is provided (works correctly for compiled go applications). ### Framework Supported -* [http/net](.../../../http-net/README.md) +* [http/net](../../net/http/README.md) - basic support +* [gorrila/mux](../../gorrila//mux/README.md) - proper support ## Options diff --git a/go/gorrila/mux/README.md b/go/gorrila/mux/README.md new file mode 100644 index 00000000..afd09ac0 --- /dev/null +++ b/go/gorrila/mux/README.md @@ -0,0 +1,96 @@ +# go-sql-driver + +SQLcommenter is a plugin/middleware/wrapper to augment application related information/tags with SQL Statements that can be used later to correlate user code with SQL statements. + +## Installation + +```shell +go get -u github.com/google/sqlcommenter/go/gorrila/mux +``` + +## Usage + +This library provides a middleware that extracts SQLCommenter HTTP request tags from a request being handled by `gorrila/mux` and attaches them to the request's context. This same context, when used to run queries using [sqlcommenter/go/database/sql](../../database/sql/README.md), allows request tags and traceparent (if using the [otelmux](https://github.com/open-telemetry/opentelemetry-go-contrib/tree/main/instrumentation/github.com/gorilla/mux/otelmux)) to be passed into SQL comments. + + +## Example + +```go +import ( + "net/http" + + sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux" + "github.com/gorilla/mux" +) + +func runApp() { + r := mux.NewRouter() + r.Use(sqlcommentermux.SQLCommenterMiddleware) + + r.HandleFunc("/", ActionHome).Methods("GET") + + http.ListenAndServe(":8081", r) +} +``` + +## Example (with otelmux) + +```go +import ( + "context" + "log" + "net/http" + + sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux" + "github.com/gorilla/mux" + "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux" + "go.opentelemetry.io/otel" + stdout "go.opentelemetry.io/otel/exporters/stdout/stdouttrace" + "go.opentelemetry.io/otel/propagation" + sdktrace "go.opentelemetry.io/otel/sdk/trace" +) + +func main() { + tp, err := initTracer() + if err != nil { + log.Fatal(err) + } + defer func() { + if err := tp.Shutdown(context.Background()); err != nil { + log.Printf("Error shutting down tracer provider: %v", err) + } + }() + + r := mux.NewRouter() + r.Use(otelmux.Middleware("sqlcommenter sample-server"), sqlcommentermux.SQLCommenterMiddleware) + + r.HandleFunc("/", ActionHome).Methods("GET") + + http.ListenAndServe(":8081", r) +} + +func initTracer() (*sdktrace.TracerProvider, error) { + exporter, err := stdout.New(stdout.WithPrettyPrint()) + if err != nil { + return nil, err + } + tp := sdktrace.NewTracerProvider( + sdktrace.WithSampler(sdktrace.AlwaysSample()), + sdktrace.WithBatcher(exporter), + ) + otel.SetTracerProvider(tp) + otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{})) + return tp, nil +} +``` + +## Options + +With Go SqlCommenter, we have configuration to choose which tags to be appended to the comment. + +| Options | Included by default? | gorrila/mux | +| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `Action` | | name of the handler function | +| `Route` | | [routing path](https://pkg.go.dev/github.com/gorilla/mux#Route.GetPathTemplate) | +| `Framework` | | gorrila/mux | +| `Opentelemetry` | | [W3C TraceContext.Traceparent](https://www.w3.org/TR/trace-context/#traceparent-field), [W3C TraceContext.Tracestate](https://www.w3.org/TR/trace-context/#tracestate-field) | diff --git a/go/net/http/README.md b/go/net/http/README.md index 6c148954..612fa89f 100644 --- a/go/net/http/README.md +++ b/go/net/http/README.md @@ -1,71 +1,25 @@ -# http-net [In development] +# SQLCommenter http-net [In development] SQLcommenter is a plugin/middleware/wrapper to augment application related information/tags with SQL Statements that can be used later to correlate user code with SQL statements. ## Installation -### Install from source - -* Clone the source -* In terminal go inside the client folder location where we need to import sqlcommenter http/net module and enter the below commands - -```shell -go mod edit -replace google.com/sqlcommenter=path/to/google/sqlcommenter/http-net - -go mod tiny - -go get google.com/sqlcommenter/http-net +```bash +go get -u github.com/google/sqlcommenter/go/net/http ``` -### Install from github [To be added] ## Usage -Please use the sqlcommenter's default go-sql database driver to execute statements. \ -Due to inherent nature of Go, the safer way to pass information from framework to database driver is via `context`. So, it is recommended to use the context based methods of `DB` interface like `QueryContext`, `ExecContext` and `PrepareContext`. - -```go -db, err := gosql.Open("", "", sqlcommenter.CommenterOptions{:}) -``` - -### Configuration - -Users are given control over what tags they want to append by using `core.CommenterOptions` struct. +This is a low-level package that can be used to prepare SQLCommeneterTags out of an http request. The core package can then be used to inject these tags into a context ```go -type CommenterOptions struct { - EnableDBDriver bool - EnableTraceparent bool // OpenTelemetry trace information - EnableRoute bool // applicable for web frameworks - EnableFramework bool // applicable for web frameworks - EnableController bool // applicable for web frameworks - EnableAction bool // applicable for web frameworks - } -``` - +import ( + sqlcommenterhttp "github.com/google/sqlcommenter/go/net/http" +) -#### Note -* We only support the `database/sql` driver and have provided an implementation for that. -* ORM related tags are added to the driver only when the tags are enabled in the commenter's driver's config and also the request context should passed to the querying functions -* The middleware implementing this sqlcommenter http-net module should be added at the last - -#### Example -```go -// middleware is used to intercept incoming HTTP calls and populate request context with commenter tags. -func middleware(next http.Handler) http.Handler { - return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { - ctx := httpnet.NewHttpNet(r, next).AddTags(r.Context()) - next.ServeHTTP(w, r.WithContext(ctx)) - }) -} +requestTags := sqlcommenterhttp.NewHTTPRequestTags(framework string, route string, action string) +ctx := core.ContextInject(request.Context(), requestTags) +requestWithTags := request.WithContext(ctx) ``` -## Options - -With Go SqlCommenter, we have configuration to choose which tags to be appended to the comment. - -| Options | Included by default? | net/http | -| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Action` | | [net/http handle](https://pkg.go.dev/net/http#Handle) | -| `Route` | | [net/http routing path](https://pkg.go.dev/github.com/gorilla/mux#Route.URLPath) | -| `Framework` | | [net/http](https://pkg.go.dev/net/http) | -| `Opentelemetry` | | [W3C TraceContext.Traceparent](https://www.w3.org/TR/trace-context/#traceparent-field), [W3C TraceContext.Tracestate](https://www.w3.org/TR/trace-context/#tracestate-field) | +This package can be used to instrument SQLCommenter for various frameworks. \ No newline at end of file From 41431ddfb00b273356be7ba221dcbb8fea47af08 Mon Sep 17 00:00:00 2001 From: Kapil Verma Date: Wed, 23 Nov 2022 17:45:02 +0530 Subject: [PATCH 2/2] docs fixes --- go/core/README.md | 22 ++++++------- go/database/sql/README.md | 30 ++++++++--------- go/gorrila/mux/README.md | 68 +++++++++++++++++++-------------------- go/net/http/README.md | 2 +- 4 files changed, 61 insertions(+), 61 deletions(-) diff --git a/go/core/README.md b/go/core/README.md index eaec9bad..98ddf424 100644 --- a/go/core/README.md +++ b/go/core/README.md @@ -16,13 +16,13 @@ Users are given control over what tags they want to append by using `core.Commen ```go type CommenterConfig struct { - EnableDBDriver bool - EnableRoute bool - EnableFramework bool - EnableController bool - EnableAction bool - EnableTraceparent bool - EnableApplication bool + EnableDBDriver bool + EnableRoute bool + EnableFramework bool + EnableController bool + EnableAction bool + EnableTraceparent bool + EnableApplication bool } ``` @@ -30,8 +30,8 @@ Users can also set the values for some static tags by using `core.StaticTags` st ```go type StaticTags struct { - Application string - DriverName string + Application string + DriverName string } ``` @@ -39,7 +39,7 @@ These two structs together form the `core.CommenterOptions` struct, which is use ```go type CommenterOptions struct { - Config CommenterConfig - Tags StaticTags + Config CommenterConfig + Tags StaticTags } ``` \ No newline at end of file diff --git a/go/database/sql/README.md b/go/database/sql/README.md index 9459083d..459fdf41 100644 --- a/go/database/sql/README.md +++ b/go/database/sql/README.md @@ -15,14 +15,14 @@ Due to inherent nature of Go, the safer way to pass information from framework t ```go import ( - gosql "github.com/google/sqlcommenter/go/database/sql" - sqlcommentercore "github.com/google/sqlcommenter/go/core" - _ "github.com/lib/pq" // or any other database driver + gosql "github.com/google/sqlcommenter/go/database/sql" + sqlcommentercore "github.com/google/sqlcommenter/go/core" + _ "github.com/lib/pq" // or any other database driver ) db, err := gosql.Open("", "", sqlcommentercore.CommenterOptions{ - Config: sqlcommentercore.CommenterConfig{:bool} - Tags : sqlcommentercore.StaticTags{: string} // optional + Config: sqlcommentercore.CommenterConfig{:bool} + Tags : sqlcommentercore.StaticTags{: string} // optional }) ``` @@ -32,22 +32,22 @@ Users are given control over what tags they want to append by using `core.Commen ```go type CommenterOptions struct { - EnableDBDriver bool - EnableTraceparent bool // OpenTelemetry trace information - EnableRoute bool // applicable for web frameworks - EnableFramework bool // applicable for web frameworks - EnableController bool // applicable for web frameworks - EnableAction bool // applicable for web frameworks - EnableApplication bool // applicable for web frameworks + EnableDBDriver bool + EnableTraceparent bool // OpenTelemetry trace information + EnableRoute bool // applicable for web frameworks + EnableFramework bool // applicable for web frameworks + EnableController bool // applicable for web frameworks + EnableAction bool // applicable for web frameworks + EnableApplication bool // applicable for web frameworks } ``` -Users can also provide static tags they want to use by using `core.StaticTags` struct. These tags are optional +Users can also provide static tags they want to use by using `core.StaticTags` struct. These tags are optional. If not provided, the `Application` tag will get auto-populated from the user-project's module-name in `go.mod`. `DriverName` is set to the driver-name provided in `gosql.Open(driverName, ...)` call. ```go type StaticTags struct { - Application string - DriverName string + Application string + DriverName string } ``` diff --git a/go/gorrila/mux/README.md b/go/gorrila/mux/README.md index afd09ac0..0e533a9e 100644 --- a/go/gorrila/mux/README.md +++ b/go/gorrila/mux/README.md @@ -20,14 +20,14 @@ import ( "net/http" sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux" - "github.com/gorilla/mux" + "github.com/gorilla/mux" ) func runApp() { - r := mux.NewRouter() - r.Use(sqlcommentermux.SQLCommenterMiddleware) + r := mux.NewRouter() + r.Use(sqlcommentermux.SQLCommenterMiddleware) - r.HandleFunc("/", ActionHome).Methods("GET") + r.HandleFunc("/", ActionHome).Methods("GET") http.ListenAndServe(":8081", r) } @@ -38,49 +38,49 @@ func runApp() { ```go import ( "context" - "log" - "net/http" + "log" + "net/http" sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux" - "github.com/gorilla/mux" - "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux" - "go.opentelemetry.io/otel" - stdout "go.opentelemetry.io/otel/exporters/stdout/stdouttrace" - "go.opentelemetry.io/otel/propagation" - sdktrace "go.opentelemetry.io/otel/sdk/trace" + "github.com/gorilla/mux" + "go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux" + "go.opentelemetry.io/otel" + stdout "go.opentelemetry.io/otel/exporters/stdout/stdouttrace" + "go.opentelemetry.io/otel/propagation" + sdktrace "go.opentelemetry.io/otel/sdk/trace" ) func main() { tp, err := initTracer() - if err != nil { - log.Fatal(err) - } - defer func() { - if err := tp.Shutdown(context.Background()); err != nil { - log.Printf("Error shutting down tracer provider: %v", err) - } - }() + if err != nil { + log.Fatal(err) + } + defer func() { + if err := tp.Shutdown(context.Background()); err != nil { + log.Printf("Error shutting down tracer provider: %v", err) + } + }() - r := mux.NewRouter() - r.Use(otelmux.Middleware("sqlcommenter sample-server"), sqlcommentermux.SQLCommenterMiddleware) + r := mux.NewRouter() + r.Use(otelmux.Middleware("sqlcommenter sample-server"), sqlcommentermux.SQLCommenterMiddleware) - r.HandleFunc("/", ActionHome).Methods("GET") + r.HandleFunc("/", ActionHome).Methods("GET") http.ListenAndServe(":8081", r) } func initTracer() (*sdktrace.TracerProvider, error) { - exporter, err := stdout.New(stdout.WithPrettyPrint()) - if err != nil { - return nil, err - } - tp := sdktrace.NewTracerProvider( - sdktrace.WithSampler(sdktrace.AlwaysSample()), - sdktrace.WithBatcher(exporter), - ) - otel.SetTracerProvider(tp) - otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{})) - return tp, nil + exporter, err := stdout.New(stdout.WithPrettyPrint()) + if err != nil { + return nil, err + } + tp := sdktrace.NewTracerProvider( + sdktrace.WithSampler(sdktrace.AlwaysSample()), + sdktrace.WithBatcher(exporter), + ) + otel.SetTracerProvider(tp) + otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{})) + return tp, nil } ``` diff --git a/go/net/http/README.md b/go/net/http/README.md index 612fa89f..2268dfd9 100644 --- a/go/net/http/README.md +++ b/go/net/http/README.md @@ -14,7 +14,7 @@ This is a low-level package that can be used to prepare SQLCommeneterTags out of ```go import ( - sqlcommenterhttp "github.com/google/sqlcommenter/go/net/http" + sqlcommenterhttp "github.com/google/sqlcommenter/go/net/http" ) requestTags := sqlcommenterhttp.NewHTTPRequestTags(framework string, route string, action string)