{"id":19054539,"url":"https://github.com/datadog/pg_tracing","last_synced_at":"2025-04-24T03:21:46.137Z","repository":{"id":228775950,"uuid":"771925717","full_name":"DataDog/pg_tracing","owner":"DataDog","description":"Distributed Tracing for PostgreSQL","archived":false,"fork":false,"pushed_at":"2025-03-24T13:59:44.000Z","size":466,"stargazers_count":64,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-18T12:17:25.303Z","etag":null,"topics":["distributed-tracing","postgresql","tracing"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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}},"created_at":"2024-03-14T07:56:08.000Z","updated_at":"2025-04-14T16:54:03.000Z","dependencies_parsed_at":"2024-04-15T08:56:34.190Z","dependency_job_id":null,"html_url":"https://github.com/DataDog/pg_tracing","commit_stats":null,"previous_names":["datadog/pg_tracing"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fpg_tracing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fpg_tracing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fpg_tracing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fpg_tracing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/pg_tracing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250552781,"owners_count":21449274,"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":["distributed-tracing","postgresql","tracing"],"created_at":"2024-11-08T23:38:42.146Z","updated_at":"2025-04-24T03:21:46.114Z","avatar_url":"https://github.com/DataDog.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pg_tracing\n\n![nested_loop trace](https://gist.githubusercontent.com/bonnefoa/c4204828fff8ff1d4ed2b275fbbbdfaa/raw/313dd65703aba3a53da5eaacd1c447ef64ec7bef/nested_loop.png)\n\npg_tracing is a PostgreSQL extension that generates server-side spans for distributed tracing.\n\nWhen pg_tracing is active, it generates spans on sampled queries. To access these spans, the extension provides two ways:\n- `pg_tracing_consume_spans` and `pg_tracing_peek_spans` views output spans as a set of records\n- `pg_tracing_json_spans` function outputs spans as a OTLP json\n\nThe utility functions `pg_tracing_reset` and `pg_tracing_info` provide ways to read and reset extension's statistics. These are not available globally but can be enabled for a specific database with `CREATE EXTENSION pg_tracing`.\n\nThere are currently two mechanisms to propagate trace context:\n- As a SQL comment using [SQLCommenter](https://google.github.io/sqlcommenter/)\n- As a GUC parameter `pg_tracing.trace_context`\n\nSee [Trace Propagation](#trace-propagation) for more details.\n\n\u003e [!WARNING]\n\u003e This extension is still in early development and may be unstable.\n\n## PostgreSQL Version Compatibility\n\npg_tracing only supports PostgreSQL 15 and 16 for the moment.\n\n## Generated Spans\n\npg_tracing generates spans for the following events:\n\n- PostgreSQL internal functions: Planner, ProcessUtility, ExecutorRun, ExecutorFinish\n- Statements: SELECT, INSERT, DELETE...\n- Utility Statements: ALTER, SHOW, TRUNCATE, CALL...\n- Execution Plan: A span is created for each node of the execution plan (SeqScan, NestedLoop, HashJoin...)\n- Nested queries: Statements invoked within another statement (like a function)\n- Triggers: Statements executed through BEFORE and AFTER trigger are tracked\n- Parallel Workers: Processes created to handle queries like Parallel SeqScans are tracked\n- Transaction Commit: Time spent fsync changes on the WAL\n\n## Documentation\n\nThe following list of files is found in the [doc](doc) folder of the pg_tracing github repository. For [installation instructions](#installation), please see the next section of this README.\n\n| File                                                              | Description                                                                   |\n|-------------------------------------------------------------------|-------------------------------------------------------------------------------|\n| [pg_tracing.md](doc/pg_tracing.md)                                | Main reference documentation for pg_tracing.                                  |\n\n\n## Installation\n\n### From Source\n\npg_tracing can be compiled against an installed copy of PostgreSQL with development packages using `PGXS`.\n\nTo compile and install the extension, run:\n\n```bash\ngit clone https://github.com/DataDog/pg_tracing.git\ncd pg_tracing\nmake install\n# To compile and install with debug symbols:\nPG_CFLAGS=\"-g\" make install\n```\n\n## Setup\n\nThe extension must be loaded by adding pg_tracing to the [shared_preload_libraries](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES) in `postgresql.conf`.\nA server restart is needed to add or remove the extension.\n\n```\n# postgresql.conf\nshared_preload_libraries = 'pg_tracing'\n\ncompute_query_id = on\npg_tracing.max_span = 10000\npg_tracing.track = all\n\n# Send spans every 2 seconds to an otel collector\npg_tracing.otel_endpoint = http://127.0.0.1:4318/v1/traces\npg_tracing.otel_naptime = 2000\n```\n\nThe extension requires additional shared memory proportional to `pg_tracing.max_span`. Note that this memory is consumed whenever the extension is loaded, even if no spans are generated.\n\n## Trace Propagation\n\n### SQLCommenter\n\nTrace context can be propagated through [SQLCommenter](https://google.github.io/sqlcommenter/). By default, all queries with a SQLCommenter with a sampled flag enabled will generate spans.\n\n```sql\n-- Query with trace context and sampled flag enable\n/*traceparent='00-00000000000000000000000000000123-0000000000000123-01'*/ SELECT 1;\n\n-- Check the generated spans\nselect trace_id, parent_id, span_id, span_start, span_end, span_type, span_operation from pg_tracing_consume_spans order by span_start;\n             trace_id             |    parent_id     |     span_id      |          span_start           |           span_end            |  span_type   | span_operation\n----------------------------------+------------------+------------------+-------------------------------+-------------------------------+--------------+----------------\n 00000000000000000000000000000123 | 0000000000000123 | 4268a4281c5316dd | 2024-03-19 13:46:43.97958+00  | 2024-03-19 13:46:43.980121+00 | Select query | SELECT $1;\n 00000000000000000000000000000123 | 4268a4281c5316dd | 87cb96b6459880a0 | 2024-03-19 13:46:43.979642+00 | 2024-03-19 13:46:43.979978+00 | Planner      | Planner\n 00000000000000000000000000000123 | 4268a4281c5316dd | f5994f9159d8e80d | 2024-03-19 13:46:43.980081+00 | 2024-03-19 13:46:43.980111+00 | Executor     | ExecutorRun\n```\n\n### `trace_context` GUC\n\nThe GUC variable `pg_tracing.trace_context` can also be used to propagate trace context.\n\n```sql\nBEGIN;\nSET LOCAL pg_tracing.trace_context='traceparent=''00-00000000000000000000000000000005-0000000000000005-01''';\nUPDATE pgbench_accounts SET abalance=1 where aid=1;\nCOMMIT;\n\n-- Check generated span\nselect trace_id, span_start, span_end, span_type, span_operation from pg_tracing_consume_spans order by span_start;\n             trace_id             |          span_start           |           span_end            |     span_type     |                      span_operation\n----------------------------------+-------------------------------+-------------------------------+-------------------+-----------------------------------------------------------\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.305234+00 | 2024-07-05 14:24:55.305988+00 | Update query      | UPDATE pgbench_accounts SET abalance=$1 where aid=$2;\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.305266+00 | 2024-07-05 14:24:55.30552+00  | Planner           | Planner\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.305586+00 | 2024-07-05 14:24:55.305906+00 | ExecutorRun       | ExecutorRun\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.305591+00 | 2024-07-05 14:24:55.305903+00 | Update            | Update on pgbench_accounts\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.305593+00 | 2024-07-05 14:24:55.305806+00 | IndexScan         | IndexScan using pgbench_accounts_pkey on pgbench_accounts\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.649757+00 | 2024-07-05 14:24:55.649792+00 | Utility query     | COMMIT;\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.649787+00 | 2024-07-05 14:24:55.649792+00 | ProcessUtility    | ProcessUtility\n 00000000000000000000000000000005 | 2024-07-05 14:24:55.649816+00 | 2024-07-05 14:24:55.650613+00 | TransactionCommit | TransactionCommit\n```\n\n### Standalone Sampling\n\nQueries can also be sampled randomly through the `pg_tracing.sample_rate` parameter. Setting this to 1 will trace all queries.\n\n```sql\n-- Enable tracing for all queries\nSET pg_tracing.sample_rate = 1.0;\n\n-- Execute a query that will be traced\nSELECT 1;\n\n-- Check generated spans\nselect trace_id, parent_id, span_id, span_start, span_end, span_type, span_operation from pg_tracing_consume_spans order by span_start;\n             trace_id             |    parent_id     |     span_id      |          span_start           |           span_end            |  span_type   | span_operation\n----------------------------------+------------------+------------------+-------------------------------+-------------------------------+--------------+----------------\n 458fbefd7034e670eb3d9c930862c378 | eb3d9c930862c378 | bdecb6e35d429f3d | 2024-01-10 09:54:16.321253+00 | 2024-01-10 09:54:16.321587+00 | Select query | SELECT $1;\n 458fbefd7034e670eb3d9c930862c378 | bdecb6e35d429f3d | ad49f27543b0175d | 2024-01-10 09:54:16.3213+00   | 2024-01-10 09:54:16.321412+00 | Planner      | Planner\n 458fbefd7034e670eb3d9c930862c378 | bdecb6e35d429f3d | 8805f7749249536b | 2024-01-10 09:54:16.321485+00 | 2024-01-10 09:54:16.321529+00 | Executor     | ExecutorRun\n```\n\n## Sending Spans\n\nSpans can be automatically sent to an otel collector by setting the `pg_tracing.otel_endpoint` parameter:\n\n```\n# postgresql.conf\npg_tracing.otel_endpoint = http://127.0.0.1:4318/v1/traces\npg_tracing.otel_naptime = 2000\n```\n\nIf an otel endpoint is defined, a background worker will be started and will send spans every $naptime using the OTLP HTTP/JSON protocol.\nThe endpoint can be changed while the server is running, but if it was not set when the server was started, changing it to non-empty value\nrequires a restart.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fpg_tracing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fpg_tracing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fpg_tracing/lists"}