|
| 1 | +# SlowSQL Connector |
| 2 | + |
| 3 | +<!-- status autogenerated section --> |
| 4 | +| Status | | |
| 5 | +| ------------- |-----------| |
| 6 | +| Distributions | [] | |
| 7 | +| Issues | [](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Aconnector%2Fslowsql) [](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Aconnector%2Fslowsql) | |
| 8 | +| Code coverage | [](https://app.codecov.io/gh/open-telemetry/opentelemetry-collector-contrib/tree/main/?components%5B0%5D=connector_slowsql&displayType=list) | |
| 9 | +| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner) | [@JaredTan95](https://www.github.com/JaredTan95), [@Frapschen](https://www.github.com/Frapschen), [@atoulme](https://www.github.com/atoulme) | |
| 10 | + |
| 11 | +[development]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#development |
| 12 | + |
| 13 | +## Supported Pipeline Types |
| 14 | + |
| 15 | +| [Exporter Pipeline Type] | [Receiver Pipeline Type] | [Stability Level] | |
| 16 | +| ------------------------ | ------------------------ | ----------------- | |
| 17 | +| traces | logs | [development] | |
| 18 | + |
| 19 | +[Exporter Pipeline Type]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md#exporter-pipeline-type |
| 20 | +[Receiver Pipeline Type]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md#receiver-pipeline-type |
| 21 | +[Stability Level]: https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/component-stability.md#stability-levels |
| 22 | +<!-- end autogenerated section --> |
| 23 | + |
| 24 | +## Overview |
| 25 | + |
| 26 | +Generate logs from recorded [slow database statement](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-spans.md/) associated with spans. |
| 27 | + |
| 28 | +Each **log** will have _at least_ the following dimensions: |
| 29 | +- Service name |
| 30 | +- Span kind |
| 31 | +- Span name |
| 32 | +- Status code |
| 33 | +- Trace ID |
| 34 | +- Span ID |
| 35 | +- Database System |
| 36 | +- Database Statement |
| 37 | +- Database Statement Duration |
| 38 | + |
| 39 | +Each log will additionally have the following attributes: |
| 40 | +- Span attributes. If you want to filter out some attributes (like only copying HTTP attributes starting with `http.`) use the [transform processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor/). |
| 41 | + |
| 42 | +## Configurations |
| 43 | + |
| 44 | +If you are not already familiar with connectors, you may find it helpful to first visit the [Connectors README]. |
| 45 | + |
| 46 | +The following settings can be optionally configured: |
| 47 | +- `dimensions`: the list of dimensions to add to *logs* with the default dimensions defined above. |
| 48 | + Each additional dimension is defined with a `name` which is looked up in the span's collection of attributes or |
| 49 | + resource attributes (AKA process tags) such as `ip`, `host.name` or `region`. |
| 50 | +- `db_system:` the list value of span attribute `db.system`, Filter specific db systems, define those database's statements need to be collected. ref: https://opentelemetry.io/docs/specs/semconv/attributes-registry/db/ |
| 51 | + - Default: `[h2, mongodb, mssql, mysql, oracle, postgresql, mariadb]` |
| 52 | +- `threshold`: define a threshold and collect when the `db.statement`, namely span duration, larger than this value. |
| 53 | + - Default: `500ms` |
| 54 | + |
| 55 | +## Examples |
| 56 | + |
| 57 | +The following is a simple example usage of the `slow sql` connector. |
| 58 | + |
| 59 | +```yaml |
| 60 | +receivers: |
| 61 | + nop: |
| 62 | + |
| 63 | +exporters: |
| 64 | + nop: |
| 65 | + |
| 66 | +connectors: |
| 67 | + slowsql: |
| 68 | + threshold: 600ms |
| 69 | + dimensions: |
| 70 | + - name: k8s.namespace.name |
| 71 | + - name: k8s.pod.name |
| 72 | + |
| 73 | +service: |
| 74 | + pipelines: |
| 75 | + traces: |
| 76 | + receivers: [nop] |
| 77 | + exporters: [slowsql] |
| 78 | + logs: |
| 79 | + receivers: [slowsql] |
| 80 | + exporters: [nop] |
| 81 | +``` |
| 82 | +
|
| 83 | +The following is a more complex example usage of the `slowsql` connector using Elasticsearch as exporters. |
| 84 | + |
| 85 | +```yaml |
| 86 | +receivers: |
| 87 | + otlp: |
| 88 | + protocols: |
| 89 | + grpc: |
| 90 | + http: |
| 91 | +
|
| 92 | +exporters: |
| 93 | + elasticsearch/slow_sql: |
| 94 | + tls: |
| 95 | + insecure: true |
| 96 | + mapping: |
| 97 | + mode: raw |
| 98 | + endpoints: |
| 99 | + - http://localhost:9200 |
| 100 | + user: elastic |
| 101 | + password: elastic |
| 102 | +
|
| 103 | +connectors: |
| 104 | + slowsql: |
| 105 | + threshold: 600ms |
| 106 | + dimensions: |
| 107 | + - name: k8s.namespace.name |
| 108 | + - name: k8s.pod.name |
| 109 | +
|
| 110 | +service: |
| 111 | + pipelines: |
| 112 | + traces: |
| 113 | + receivers: [otl[]] |
| 114 | + exporters: [slowsql] |
| 115 | + logs: |
| 116 | + receivers: [slowsql] |
| 117 | + exporters: [elasticsearch/slow_sql] |
| 118 | +``` |
| 119 | + |
| 120 | +The full list of settings exposed for this connector is documented in [slowsqlconnector/config.go](../../connector/slowsqlconnector/config.go). |
| 121 | +### More Examples |
| 122 | + |
| 123 | +For more example configuration covering various other use cases, please visit the [testdata directory](../../connector/slowsqlconnector/testdata). |
| 124 | + |
| 125 | +[Connectors README]:https://github.com/open-telemetry/opentelemetry-collector/blob/main/connector/README.md |
0 commit comments