{"id":21674513,"url":"https://github.com/j2gg0s/otsql","last_synced_at":"2025-04-12T04:22:28.626Z","repository":{"id":38250755,"uuid":"294405176","full_name":"j2gg0s/otsql","owner":"j2gg0s","description":"Go sqldriver's hook, support opentelemetry \u0026 prometheus.","archived":false,"fork":false,"pushed_at":"2024-03-25T11:01:58.000Z","size":145,"stargazers_count":23,"open_issues_count":5,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-25T23:51:25.293Z","etag":null,"topics":["hook","metric","opentelemetry","prometheus","sql","trace"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/j2gg0s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-09-10T12:37:22.000Z","updated_at":"2025-01-10T00:56:15.000Z","dependencies_parsed_at":"2024-06-18T18:23:16.169Z","dependency_job_id":"10d3e99f-ebc5-4be0-b2c6-97cb37368e18","html_url":"https://github.com/j2gg0s/otsql","commit_stats":null,"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j2gg0s%2Fotsql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j2gg0s%2Fotsql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j2gg0s%2Fotsql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j2gg0s%2Fotsql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/j2gg0s","download_url":"https://codeload.github.com/j2gg0s/otsql/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248514561,"owners_count":21116983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hook","metric","opentelemetry","prometheus","sql","trace"],"created_at":"2024-11-25T13:48:00.466Z","updated_at":"2025-04-12T04:22:28.596Z","avatar_url":"https://github.com/j2gg0s.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# otsql\n\n[![Docs](https://godoc.org/github.com/j2gg0s/otsql?status.svg)](https://pkg.go.dev/github.com/j2gg0s/otsql)\n[![Go Report Card](https://goreportcard.com/badge/github.com/j2gg0s/otsql)](https://goreportcard.com/report/github.com/j2gg0s/otsql)\n\nAdd an otsql wrapper to your existing database code to hook any sql command.\n\n-   Support tracing with [OpenTelemetry](https://opentelemetry.io/) by [otsql/hook/trace](https://github.com/j2gg0s/otsql/tree/bun/hook/metric).\n-   Support monitor latency and connection pool stats with [Prometheus](https://github.com/prometheus/prometheus)\n    by [otsql/hook/metric](https://github.com/j2gg0s/otsql/tree/bun/hook/metric).\n-   Support acess log with [zerolog](https://github.com/rs/zerolog) by [otsql/hook/trace](https://github.com/j2gg0s/otsql/tree/bun/hook/trace).\n\nFirst version transformed from [ocsql](https://github.com/opencensus-integrations/ocsql).\n\n## Install\n\n```\n$ go get -u github.com/j2gg0s/otsql\n```\n\n## Usage\n\nTo use otsql with your application, register an otsql wrapper of a database driver\nas shown below.\n\nExample:\n\n```go\nimport (\n    \"database/sql\"\n\n    \"github.com/j2gg0s/otsql\"\n    \"github.com/j2gg0s/otsql/hook/trace\"\n    \"github.com/j2gg0s/otsql/hook/metric\"\n    \"github.com/j2gg0s/otsql/hook/log\"\n    _ \"github.com/go-sql-driver/mysql\"\n)\n\nvar dsn = \"postgres://otsql_user:otsql_password@localhost/otsql_db?sslmode=disable\"\n\nmetricHook, err := metric.New()\nif err != nil {\n    return \"\", fmt.Errorf(\"new metric hook: %w\", err)\n}\n\ndriverName, err := otsql.Register(\n    name,\n    otsql.WithHooks(\n        trace.New(\n            trace.WithAllowRoot(true),\n            trace.WithQuery(true),\n            trace.WithQueryParams(true),\n        ),\n        metricHook,\n        log.New(),\n    ),\n)\nif err != nil {\n    panic(err)\n}\n\ndb, err := sql.Open(driverName, dsn)\nif err != nil {\n    panic(err)\n}\ndefer db.Close()\n```\n\nFinally database drivers that support the driver.Connector\ninterface can be wrapped directly by otsql without the need for otsql to\nregister a driver.Driver.\n\nExample:\n\n```go\nimport (\n    \"database/sql\"\n\n    \"github.com/j2gg0s/otsql\"\n    \"github.com/j2gg0s/otsql/hook/trace\"\n    _ \"github.com/lib/pq\"\n)\n\nvar dsn = \"postgres://otsql_user:otsql_password@localhost/otsql_db?sslmode=disable\"\n\nconnector, err := pq.NewConnector(dsn)\nif err != nil {\n    panic(err)\n}\n\ndb := sql.OpenDB(\n    WrapConnector(connector, otsql.Hooks(trace.new())))\ndefer db.Close()\n```\n\nSee more specific case in `example/`.\n\n## Trace with opentelemetry\n\notsql support trace with opentelemetry by `hook/trace`.\n\n## Metric with prometheus\n\notsql support metric with prometheus by `hook/metric`.\n\n| Metric                 | Search suffix  | Tags                                 |\n| ---------------------- | -------------- | ------------------------------------ |\n| Latency in millisecond | go_sql_latency | sql_instance, sql_method, sql_status |\n\nYou can use `metric.Stats` to monitor connection pool, all metric supprt tag `sql_instance`.\n| Metric | Search suffix |\n|--------|---------------|\n| The number of connections currently in use | go_sql_conn_in_use |\n| The number of idle connections | go_sql_conn_idle |\n| The total number of connections wait for | go_sql_conn_wait |\n| The total number of connections closed because of SetMaxIdleConns | go_sql_conn_idle_closed |\n| The total number of connections closed because of SetConnMaxLifetime | go_sql_conn_lifetime_closed |\n| The total time blocked by waiting for a new connection, nanosecond | go_sql_conn_wait_ns |\n\n## Test\n\nTest by [bun](https://github.com/uptrace/bun)'s unittest with a special branch [otsql@bun](https://github.com/j2gg0s/bun/tree/otsql).\n\nTest by [gorm](https://github.com/go-gorm/gorm)'s unittest with a special branch [otsql@gorm](https://github.com/j2gg0s/gorm/tree/otsql).\nIt also includes example for [pgx](https://github.com/jackc/pgx).\n\n## Benchmark\n\nRun benchmark with [bun](https://github.com/uptrace/bun):\n\n```bash\ngoos: darwin\ngoarch: amd64\npkg: github.com/uptrace/bun/internal/dbtest\ncpu: Intel(R) Core(TM) i7-8557U CPU @ 1.70GHz\nBenchmarkSelectOne/pg-8             4579            281209 ns/op\nBenchmarkSelectOne/mysql-8                  4146            292964 ns/op\nBenchmarkSelectOne/sqlite-8                37898             28012 ns/op\nBenchmarkSelectSlice/mysql-8                2874            397543 ns/op\nBenchmarkSelectSlice/sqlite-8               6517            184153 ns/op\nBenchmarkSelectSlice/pg-8                   2806            425935 ns/op\nBenchmarkSelectError/pg-8                   4027            314399 ns/op\nBenchmarkSelectError/mysql-8                2426            476420 ns/op\nBenchmarkSelectError/sqlite-8             166348              7320 ns/op\nPASS\nok      github.com/uptrace/bun/internal/dbtest  79.494s\n```\n\nRun benchmark with [otsql@bun](https://github.com/j2gg0s/bun/tree/otsql):\n\n```bash\ngoos: darwin\ngoarch: amd64\npkg: github.com/uptrace/bun/internal/dbtest\ncpu: Intel(R) Core(TM) i7-8557U CPU @ 1.70GHz\nBenchmarkSelectOne/pg-8             3014            332012 ns/op\nBenchmarkSelectOne/mysql-8                  3382            339056 ns/op\nBenchmarkSelectOne/sqlite-8                25057             46897 ns/op\nBenchmarkSelectSlice/pg-8                   2284            468973 ns/op\nBenchmarkSelectSlice/mysql-8                3074            426501 ns/op\nBenchmarkSelectSlice/sqlite-8               4725            234213 ns/op\nBenchmarkSelectError/pg-8                   3760            337402 ns/op\nBenchmarkSelectError/mysql-8                2647            485405 ns/op\nBenchmarkSelectError/sqlite-8              73551             15706 ns/op\nPASS\nok      github.com/uptrace/bun/internal/dbtest  67.224s\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj2gg0s%2Fotsql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fj2gg0s%2Fotsql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj2gg0s%2Fotsql/lists"}