-
Notifications
You must be signed in to change notification settings - Fork 81
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #199 from google/go/docs
updated docs
- Loading branch information
Showing
4 changed files
with
163 additions
and
90 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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("<driver>", "<connectionString>", sqlcommenter.CommenterOptions{<tag>:<bool>}) | ||
| ``` | ||
|
|
||
| ### 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. | ||
| * <b>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</b> | ||
| * <b>The middleware implementing this sqlcommenter http-net module should be added at the last</b> | ||
|
|
||
| #### 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. |