Skip to content

Commit 7adc837

Browse files
kapv89kapv89
authored
Merge pull request #199 from google/go/docs
updated docs
2 parents 8c282af + 41431dd commit 7adc837

File tree

4 files changed

+163
-90
lines changed

4 files changed

+163
-90
lines changed

‎go/core/README.md‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,34 @@ This is a support package and will be installed indirectly by other go sqlcommen
1212

1313
### Configuration
1414

15-
Users are given control over what tags they want to append by using `core.CommenterOptions` struct.
15+
Users are given control over what tags they want to append by using `core.CommenterConfig` struct.
1616

1717
```go
18-
type CommenterOptions struct {
19-
EnableDBDriver bool
20-
EnableTraceparent bool // OpenTelemetry trace information
21-
EnableRoute bool // applicable for web frameworks
22-
EnableFramework bool // applicable for web frameworks
23-
EnableController bool // applicable for web frameworks
24-
EnableAction bool // applicable for web frameworks
25-
EnableApplication bool
26-
Application string // user-provided application-name. optional
18+
type CommenterConfig struct {
19+
EnableDBDriver bool
20+
EnableRoute bool
21+
EnableFramework bool
22+
EnableController bool
23+
EnableAction bool
24+
EnableTraceparent bool
25+
EnableApplication bool
2726
}
2827
```
2928

29+
Users can also set the values for some static tags by using `core.StaticTags` struct.
30+
31+
```go
32+
type StaticTags struct {
33+
Application string
34+
DriverName string
35+
}
36+
```
3037

38+
These two structs together form the `core.CommenterOptions` struct, which is used by [sqlcommenter/go/database/sql](../database/sql/README.md).
39+
40+
```go
41+
type CommenterOptions struct {
42+
Config CommenterConfig
43+
Tags StaticTags
44+
}
45+
```

‎go/database/sql/README.md‎

Lines changed: 31 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,29 @@
1-
# go-sql-driver [In development]
1+
# go-sql-driver
22

33
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.
44

55
## Installation
66

7-
### Install from source
8-
9-
* Clone the source
10-
* In terminal go inside the client folder location where we need to import sqlcommenter go-sql module and enter the below commands
11-
127
```shell
13-
go mod edit -replace google.com/sqlcommenter=path/to/google/sqlcommenter/go-sql
14-
15-
go mod tiny
16-
17-
go get google.com/sqlcommenter/gosql
8+
go get -u github.com/google/sqlcommenter/go/database/sql
189
```
19-
### Install from github [To be added]
2010

2111
## Usage
2212

2313
Please use the sqlcommenter's default go-sql database driver to execute statements.
2414
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`.
2515

2616
```go
27-
db, err := gosql.Open("<driver>", "<connectionString>", sqlcommenter.CommenterOptions{<tag>:<bool>})
17+
import (
18+
gosql "github.com/google/sqlcommenter/go/database/sql"
19+
sqlcommentercore "github.com/google/sqlcommenter/go/core"
20+
_ "github.com/lib/pq" // or any other database driver
21+
)
22+
23+
db, err := gosql.Open("<driver>", "<connectionString>", sqlcommentercore.CommenterOptions{
24+
Config: sqlcommentercore.CommenterConfig{<flag>:bool}
25+
Tags : sqlcommentercore.StaticTags{<tag>: string} // optional
26+
})
2827
```
2928

3029
### Configuration
@@ -33,22 +32,31 @@ Users are given control over what tags they want to append by using `core.Commen
3332

3433
```go
3534
type CommenterOptions struct {
36-
EnableDBDriver bool
37-
EnableTraceparent bool // OpenTelemetry trace information
38-
EnableRoute bool // applicable for web frameworks
39-
EnableFramework bool // applicable for web frameworks
40-
EnableController bool // applicable for web frameworks
41-
EnableAction bool // applicable for web frameworks
42-
EnableApplication bool // applicable for web frameworks
43-
Application string // user-provided application-name. optional
44-
}
35+
EnableDBDriver bool
36+
EnableTraceparent bool // OpenTelemetry trace information
37+
EnableRoute bool // applicable for web frameworks
38+
EnableFramework bool // applicable for web frameworks
39+
EnableController bool // applicable for web frameworks
40+
EnableAction bool // applicable for web frameworks
41+
EnableApplication bool // applicable for web frameworks
42+
}
43+
```
44+
45+
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.
46+
47+
```go
48+
type StaticTags struct {
49+
Application string
50+
DriverName string
51+
}
4552
```
4653

4754
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).
4855

4956

5057
### Framework Supported
51-
* [http/net](.../../../http-net/README.md)
58+
* [http/net](../../net/http/README.md) - basic support
59+
* [gorrila/mux](../../gorrila//mux/README.md) - proper support
5260

5361

5462
## Options

‎go/gorrila/mux/README.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# go-sql-driver
2+
3+
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.
4+
5+
## Installation
6+
7+
```shell
8+
go get -u github.com/google/sqlcommenter/go/gorrila/mux
9+
```
10+
11+
## Usage
12+
13+
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.
14+
15+
16+
## Example
17+
18+
```go
19+
import (
20+
"net/http"
21+
22+
sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
23+
"github.com/gorilla/mux"
24+
)
25+
26+
func runApp() {
27+
r := mux.NewRouter()
28+
r.Use(sqlcommentermux.SQLCommenterMiddleware)
29+
30+
r.HandleFunc("/", ActionHome).Methods("GET")
31+
32+
http.ListenAndServe(":8081", r)
33+
}
34+
```
35+
36+
## Example (with otelmux)
37+
38+
```go
39+
import (
40+
"context"
41+
"log"
42+
"net/http"
43+
44+
sqlcommentermux "github.com/google/sqlcommenter/go/gorrila/mux"
45+
"github.com/gorilla/mux"
46+
"go.opentelemetry.io/contrib/instrumentation/github.com/gorilla/mux/otelmux"
47+
"go.opentelemetry.io/otel"
48+
stdout "go.opentelemetry.io/otel/exporters/stdout/stdouttrace"
49+
"go.opentelemetry.io/otel/propagation"
50+
sdktrace "go.opentelemetry.io/otel/sdk/trace"
51+
)
52+
53+
func main() {
54+
tp, err := initTracer()
55+
if err != nil {
56+
log.Fatal(err)
57+
}
58+
defer func() {
59+
if err := tp.Shutdown(context.Background()); err != nil {
60+
log.Printf("Error shutting down tracer provider: %v", err)
61+
}
62+
}()
63+
64+
r := mux.NewRouter()
65+
r.Use(otelmux.Middleware("sqlcommenter sample-server"), sqlcommentermux.SQLCommenterMiddleware)
66+
67+
r.HandleFunc("/", ActionHome).Methods("GET")
68+
69+
http.ListenAndServe(":8081", r)
70+
}
71+
72+
func initTracer() (*sdktrace.TracerProvider, error) {
73+
exporter, err := stdout.New(stdout.WithPrettyPrint())
74+
if err != nil {
75+
return nil, err
76+
}
77+
tp := sdktrace.NewTracerProvider(
78+
sdktrace.WithSampler(sdktrace.AlwaysSample()),
79+
sdktrace.WithBatcher(exporter),
80+
)
81+
otel.SetTracerProvider(tp)
82+
otel.SetTextMapPropagator(propagation.NewCompositeTextMapPropagator(propagation.TraceContext{}, propagation.Baggage{}))
83+
return tp, nil
84+
}
85+
```
86+
87+
## Options
88+
89+
With Go SqlCommenter, we have configuration to choose which tags to be appended to the comment.
90+
91+
| Options | Included by default? | gorrila/mux |
92+
| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93+
| `Action` | | name of the handler function |
94+
| `Route` | | [routing path](https://pkg.go.dev/github.com/gorilla/mux#Route.GetPathTemplate) |
95+
| `Framework` | | gorrila/mux |
96+
| `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) |

‎go/net/http/README.md‎

Lines changed: 11 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,25 @@
1-
# http-net [In development]
1+
# SQLCommenter http-net [In development]
22

33
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.
44

55
## Installation
66

7-
### Install from source
8-
9-
* Clone the source
10-
* In terminal go inside the client folder location where we need to import sqlcommenter http/net module and enter the below commands
11-
12-
```shell
13-
go mod edit -replace google.com/sqlcommenter=path/to/google/sqlcommenter/http-net
14-
15-
go mod tiny
16-
17-
go get google.com/sqlcommenter/http-net
7+
```bash
8+
go get -u github.com/google/sqlcommenter/go/net/http
189
```
19-
### Install from github [To be added]
2010

2111
## Usage
2212

23-
Please use the sqlcommenter's default go-sql database driver to execute statements. \
24-
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`.
25-
26-
```go
27-
db, err := gosql.Open("<driver>", "<connectionString>", sqlcommenter.CommenterOptions{<tag>:<bool>})
28-
```
29-
30-
### Configuration
31-
32-
Users are given control over what tags they want to append by using `core.CommenterOptions` struct.
13+
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
3314

3415
```go
35-
type CommenterOptions struct {
36-
EnableDBDriver bool
37-
EnableTraceparent bool // OpenTelemetry trace information
38-
EnableRoute bool // applicable for web frameworks
39-
EnableFramework bool // applicable for web frameworks
40-
EnableController bool // applicable for web frameworks
41-
EnableAction bool // applicable for web frameworks
42-
}
43-
```
44-
16+
import (
17+
sqlcommenterhttp "github.com/google/sqlcommenter/go/net/http"
18+
)
4519

46-
#### Note
47-
* We only support the `database/sql` driver and have provided an implementation for that.
48-
* <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>
49-
* <b>The middleware implementing this sqlcommenter http-net module should be added at the last</b>
50-
51-
#### Example
52-
```go
53-
// middleware is used to intercept incoming HTTP calls and populate request context with commenter tags.
54-
func middleware(next http.Handler) http.Handler {
55-
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
56-
ctx := httpnet.NewHttpNet(r, next).AddTags(r.Context())
57-
next.ServeHTTP(w, r.WithContext(ctx))
58-
})
59-
}
20+
requestTags := sqlcommenterhttp.NewHTTPRequestTags(framework string, route string, action string)
21+
ctx := core.ContextInject(request.Context(), requestTags)
22+
requestWithTags := request.WithContext(ctx)
6023
```
6124

62-
## Options
63-
64-
With Go SqlCommenter, we have configuration to choose which tags to be appended to the comment.
65-
66-
| Options | Included by default? | net/http |
67-
| --------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68-
| `Action` | | [net/http handle](https://pkg.go.dev/net/http#Handle) |
69-
| `Route` | | [net/http routing path](https://pkg.go.dev/github.com/gorilla/mux#Route.URLPath) |
70-
| `Framework` | | [net/http](https://pkg.go.dev/net/http) |
71-
| `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) |
25+
This package can be used to instrument SQLCommenter for various frameworks.

0 commit comments

Comments
 (0)