Skip to content

updated docs #199

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 23, 2022
Merged

updated docs #199

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c8c0733
updated docs
kapv89 Nov 23, 2022
41431dd
docs fixes
kapv89 Nov 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 25 additions & 10 deletions go/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
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
Application string // user-provided application-name. optional
type CommenterConfig struct {
EnableDBDriver bool
EnableRoute bool
EnableFramework bool
EnableController bool
EnableAction bool
EnableTraceparent bool
EnableApplication bool
}
```

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
}
```
54 changes: 31 additions & 23 deletions go/database/sql/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,30 +1,29 @@
# 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

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>})
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("<driver>", "<connectionString>", sqlcommentercore.CommenterOptions{
Config: sqlcommentercore.CommenterConfig{<flag>:bool}
Tags : sqlcommentercore.StaticTags{<tag>: string} // optional
})
```

### Configuration
Expand All @@ -33,22 +32,31 @@ 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
Application string // user-provided application-name. optional
}
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. 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
}
```

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
Expand Down
96 changes: 96 additions & 0 deletions go/gorrila/mux/README.md
View file
Open in desktop
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) |
68 changes: 11 additions & 57 deletions go/net/http/README.md
View file
Open in desktop
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.