SpringCloud/spring-cloud-sleuth
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Adding jdbc instrumentation (#1959)

Browse Source 
fixes gh-1930
This commit is contained in:
Marcin Grzejszczak
2021-05-26 10:00:14 +02:00
committed by GitHub
parent b591e0f474
commit 190a15de57
51 changed files with 5293 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/src/main/asciidoc/_configprops.adoc
View File

@@ -5,10 +5,10 @@
|spring.sleuth.async.enabled | `true` | Enable instrumenting async related components so that the tracing information is passed between threads.
|spring.sleuth.async.ignored-beans | | List of {@link java.util.concurrent.Executor} bean names that should be ignored and not wrapped in a trace representation.
|spring.sleuth.baggage.correlation-enabled | `true` | Enables correlating the baggage context with logging contexts.
|spring.sleuth.baggage.correlation-fields | |
|spring.sleuth.baggage.local-fields | |
|spring.sleuth.baggage.correlation-fields | | List of fields that should be propagated over the wire.
|spring.sleuth.baggage.local-fields | | List of fields that should be accessible within the JVM process but not propagated over the wire.
|spring.sleuth.baggage.remote-fields | | List of fields that are referenced the same in-process as it is on the wire. For example, the field "x-vcap-request-id" would be set as-is including the prefix.
|spring.sleuth.baggage.tag-fields | |
|spring.sleuth.baggage.tag-fields | | List of fields that should automatically become tags.
|spring.sleuth.batch.enabled | `true` | Enable Spring Batch instrumentation.
|spring.sleuth.circuitbreaker.enabled | `true` | Enable Spring Cloud CircuitBreaker instrumentation.
|spring.sleuth.config.server.enabled | `true` | Enable Spring Cloud Config Server instrumentation.
@@ -23,6 +23,27 @@
|spring.sleuth.integration.enabled | `true` | Enable Spring Integration instrumentation.
|spring.sleuth.integration.patterns | `[!hystrixStreamOutput*, *, !channel*]` | An array of patterns against which channel names will be matched. @see org.springframework.integration.config.GlobalChannelInterceptor#patterns() Defaults to any channel name not matching the Hystrix Stream and functional Stream channel names.
|spring.sleuth.integration.websockets.enabled | `true` | Enable tracing for WebSockets.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.count-query | `false` | Creates listener to count queries. @see ProxyDataSourceBuilder#countQuery() @see QueryCountHolder
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.json-format | `false` | Use json output for logging query. @see ProxyDataSourceBuilder#asJson()
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.logging | | Logging to use for logging queries.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.multiline | `true` | Use multiline output for logging query. @see ProxyDataSourceBuilder#multiline()
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.query.enable-logging | `true` | Enable logging all queries to the log.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.query.log-level | `DEBUG` | Severity of query logger.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.query.logger-name | | Name of query logger.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.slow-query.log-level | `WARN` | Severity of slow query logger.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.slow-query.logger-name | | Name of slow query logger.
|spring.sleuth.jdbc.decorator.datasource.datasource-proxy.slow-query.threshold | `300` | Number of seconds to consider query as slow.
|spring.sleuth.jdbc.decorator.datasource.enabled | `true` | Enables data source decorating.
|spring.sleuth.jdbc.decorator.datasource.excluded-beans | | Beans that won't be decorated.
|spring.sleuth.jdbc.decorator.datasource.includes | | Which types of tracing we would like to include.
|spring.sleuth.jdbc.decorator.datasource.p6spy.custom-appender-class | | Class file to use (only with logging=custom). The class must implement {@link com.p6spy.engine.spy.appender.FormattedLogger}.
|spring.sleuth.jdbc.decorator.datasource.p6spy.enable-logging | `true` | Enables logging JDBC events.
|spring.sleuth.jdbc.decorator.datasource.p6spy.log-file | `spy.log` | Name of log file to use (only with logging=file).
|spring.sleuth.jdbc.decorator.datasource.p6spy.log-filter.pattern | | Use regex pattern to filter log messages. Only matched messages will be logged.
|spring.sleuth.jdbc.decorator.datasource.p6spy.log-format | | Custom log format.
|spring.sleuth.jdbc.decorator.datasource.p6spy.logging | | Logging to use for logging queries.
|spring.sleuth.jdbc.decorator.datasource.p6spy.multiline | `true` | Enables multiline output.
|spring.sleuth.jdbc.decorator.datasource.p6spy.tracing.include-parameter-values | `true` | Report the effective sql string (with '?' replaced with real values) to tracing systems. <p> NOTE this setting does not affect the logging message.
|spring.sleuth.kafka.enabled | `true` | Enable instrumenting of Apache Kafka clients.
|spring.sleuth.messaging.aspect.enabled | `false` | Should {@link MessageMapping} wrapping be enabled.
|spring.sleuth.messaging.enabled | `false` | Should messaging be turned on.

155
docs/src/main/asciidoc/_spans.adoc
View File

@@ -292,6 +292,105 @@ Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.in
|deployer.start|When deployer started deploying the application.
|===
=== Jdbc Connection Span
> Span created when a JDBC connection takes place.
**Span name** `connection`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.jdbc.SleuthJdbcSpan`
IMPORTANT: All tags and events must be prefixed with `jdbc.` prefix!
.Tag Keys
|===
|Name | Description
|jdbc.datasource.driver|Name of the JDBC datasource driver.
|jdbc.datasource.pool|Name of the JDBC datasource pool.
|===
=== Jdbc Query Span
> Span created when a JDBC query gets executed.
**Span name** `%s` - since it contains `%s`, the name is dynamic and will be resolved at runtime.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.jdbc.SleuthJdbcSpan`
IMPORTANT: All tags and events must be prefixed with `jdbc.` prefix!
.Tag Keys
|===
|Name | Description
|jdbc.query|The SQL query value.
|jdbc.row-count|Number of SQL rows.
|===
.Event Values
|===
|Name | Description
|jdbc.commit|When the transaction gets commited.
|jdbc.rollback|When the transaction gets rolled back.
|===
=== Jdbc Result Set Span
> Span created when working with JDBC result set.
**Span name** `result-set`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.jdbc.SleuthJdbcSpan`
IMPORTANT: All tags and events must be prefixed with `jdbc.` prefix!
.Tag Keys
|===
|Name | Description
|jdbc.query|The SQL query value.
|jdbc.row-count|Number of SQL rows.
|===
.Event Values
|===
|Name | Description
|jdbc.commit|When the transaction gets commited.
|jdbc.rollback|When the transaction gets rolled back.
|===
=== Kafka Consumer Span
> Span created on the Kafka consumer side.
**Span name** `kafka.consume`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.kafka.SleuthKafkaSpan`
IMPORTANT: All tags and events must be prefixed with `kafka.` prefix!
.Tag Keys
|===
|Name | Description
|kafka.offset|Kafka offset number.
|kafka.partition|Kafka partition number.
|kafka.topic|Name of the Kafka topic.
|===
=== Kafka Producer Span
> Span created on the Kafka consumer side.
**Span name** `kafka.produce`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.kafka.SleuthKafkaSpan`
IMPORTANT: All tags and events must be prefixed with `kafka.` prefix!
.Tag Keys
|===
|Name | Description
|kafka.topic|Name of the Kafka topic.
|===
=== Messaging Span
> Span created when message is sent or received.
@@ -336,6 +435,41 @@ Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.in
|quartz.trigger|Name of the trigger.
|===
=== R2dbc Query Span
> Span created on the Kafka consumer side.
**Span name** `query`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.r2dbc.SleuthR2dbcSpan`
IMPORTANT: All tags and events must be prefixed with `r2dbc.` prefix!
.Tag Keys
|===
|Name | Description
|r2dbc.connection|Name of the R2DBC connection.
|r2dbc.query[%s]|Name of the R2DBC query. (since the name contains `%s` the final value will be resolved at runtime)
|r2dbc.thread|Name of the R2DBC thread.
|===
=== Rsocket Requester Span
> Span created on the RSocket responder side.
**Span name** `%s` - since it contains `%s`, the name is dynamic and will be resolved at runtime.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.rsocket.SleuthRSocketSpan`
IMPORTANT: All tags and events must be prefixed with `rsocket.` prefix!
.Tag Keys
|===
|Name | Description
|rsocket.request-type|Name of the R2DBC thread.
|rsocket.route|Name of the RSocket route.
|===
=== Rsocket Responder Span
> Span created on the RSocket responder side.
@@ -389,6 +523,27 @@ Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.in
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.task.SleuthTaskSpan`
=== Tx Span
> Span created when there was no previous transaction. If there was one, we will continue it unless propagation is required.
**Span name** `tx`.
Fully qualified name of the enclosing class `org.springframework.cloud.sleuth.instrument.tx.SleuthTxSpan`
IMPORTANT: All tags and events must be prefixed with `tx.` prefix!
.Tag Keys
|===
|Name | Description
|tx.isolation-level|Transaction isolation level.
|tx.name|Transaction name.
|tx.propagation-level|Transaction propagation level.
|tx.read-only|Whether the transaction is read-only.
|tx.timeout|Transaction timeout.
|tx.transaction-manager|Name of the TransactionManager.
|===
=== Web Filter Span
> Span around a WebFilter. Will continue the current span or create a new one and tag it

44
docs/src/main/asciidoc/appendix.adoc
View File

@@ -1,22 +1,22 @@
:numbered!:
[[appendix]]
[[sleuth-spans]]
== Spring Cloud Sleuth Spans
Below you can find a list of all the spans that are created by Spring Cloud Sleuth.
include::_spans.adoc[]
[[common-application-properties]]
== Common application properties
include::_attributes.adoc[]
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them.
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
Also, you can define your own properties.
include::_configprops.adoc[]
:numbered!:
[[appendix]]
[[common-application-properties]]
== Common application properties
include::_attributes.adoc[]
Various properties can be specified inside your `application.properties` file, inside your `application.yml` file, or as command line switches.
This appendix provides a list of common {project-full-name} properties and references to the underlying classes that consume them.
NOTE: Property contributions can come from additional jar files on your classpath, so you should not consider this an exhaustive list.
Also, you can define your own properties.
include::_configprops.adoc[]
[[sleuth-spans]]
== Spring Cloud Sleuth Spans
Below you can find a list of all the spans that are created by Spring Cloud Sleuth.
include::_spans.adoc[]

52
docs/src/main/asciidoc/integrations.adoc
View File

@@ -3,7 +3,7 @@
include::_attributes.adoc[]
In this section, we describe how to customize various parts of Spring Cloud Sleuth.
In this section, we describe how to customize various parts of Spring Cloud Sleuth. Please check the <<appendix.adoc#sleuth-spans,appendix>> for the list of spans, tags and events.
[[sleuth-kafka-integration]]
== Apache Kafka
@@ -650,3 +650,53 @@ This feature is available for all tracer implementations.
We're adding an instrumented Tomcat's `Valve` that originates the span.
In order to disable this instrumentation set `spring.sleuth.web.tomcat.enabled` to `false`.
[[sleuth-jdbc-integration]]
== Spring JDBC
This feature is available for all tracer implementations. It has been ported from the https://github.com/gavlyukovskiy/spring-boot-data-source-decorator/[spring-boot-datasource-decorator] project.
We're decorating `DataSource`s in a trace representation. We delegate actual proxying to either https://github.com/p6spy/p6spy[p6spy] or https://github.com/ttddyy/datasource-proxy[datasource-proxy]. In order to use this feature you need to have them on the classpath.
====
[source,xml,indent=0,subs="verbatim,attributes",role="primary"]
.P6Spy Maven
----
<dependency>
<groupId>p6spy</groupId>
<artifactId>p6spy</artifactId>
<version>${p6spy.version}</version>
<scope>runtime</scope>
</dependency>
----
[source,yml,indent=0,subs="verbatim,attributes",role="secondary"]
.P6Spy Gradle
----
runtimeOnly "p6spy:p6spy:${p6spyVersion}"
----
[source,xml,indent=0,subs="verbatim,attributes",role="secondary"]
.Datasource Proxy Maven
----
<dependency>
<groupId>net.ttddyy</groupId>
<artifactId>datasource-proxy</artifactId>
<version>${datasource-proxy.version}</version>
<scope>runtime</scope>
</dependency>
----
[source,groovy,indent=0,subs="verbatim,attributes",role="secondary"]
.Datasource Proxy Gradle
----
runtimeOnly "net.ttddyy:datasource-proxy:${datasourceProxyVersion}"
----
====
Please check the <<appendix.adoc#appendix,appendix>> page under `spring.sleuth.jdbc.decorator.datasource.p6spy` for all p6spy configuration options and `spring.sleuth.jdbc.decorator.datasource.datasource-proxy` for all datasource proxy configuration options.
You can configure P6Spy manually using one of available configuration methods. For more information please refer to the http://p6spy.readthedocs.io/en/latest/configandusage.html[P6Spy Configuration Guide].
In order to disable this instrumentation set `spring.sleuth.jdbc.decorator.datasource.enabled` to `false`.

36
docs/src/main/asciidoc/spring-cloud-sleuth.adoc
View File

@@ -1,18 +1,18 @@
[[spring-cloud-sleuth-reference-documentation]]
= Spring Cloud Sleuth Reference Documentation
Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant
:docinfo: shared
include::_attributes.adoc[]
The reference documentation consists of the following sections:
[horizontal]
<<legal.adoc#legal,Legal>> :: Legal information.
<<documentation-overview.adoc#sleuth-documentation-about,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing {project-full-name}, Developing Your First {project-full-name}-based Application
<<using.adoc#using,Using {project-full-name}>> :: {project-full-name} usage examples and workflows.
<<project-features.adoc#features,{project-full-name} Features>> :: Span creation, context propagation, and more.
<<howto.adoc#howto,"`How-to`" Guides>> :: Add sampling, propagate remote tags, and more.
<<integrations.adoc#sleuth-integration,{project-full-name} Integrations>> :: Instrumentation configuration, context propagation, and more.
<<appendix.adoc#appendix,Appendices>> :: Configuration properties.
[[spring-cloud-sleuth-reference-documentation]]
= Spring Cloud Sleuth Reference Documentation
Adrian Cole, Spencer Gibb, Marcin Grzejszczak, Dave Syer, Jay Bryant
:docinfo: shared
include::_attributes.adoc[]
The reference documentation consists of the following sections:
[horizontal]
<<legal.adoc#legal,Legal>> :: Legal information.
<<documentation-overview.adoc#sleuth-documentation-about,Documentation Overview>> :: About the Documentation, Getting Help, First Steps, and more.
<<getting-started.adoc#getting-started,Getting Started>> :: Introducing {project-full-name}, Developing Your First {project-full-name}-based Application
<<using.adoc#using,Using {project-full-name}>> :: {project-full-name} usage examples and workflows.
<<project-features.adoc#features,{project-full-name} Features>> :: Span creation, context propagation, and more.
<<howto.adoc#howto,"`How-to`" Guides>> :: Add sampling, propagate remote tags, and more.
<<integrations.adoc#sleuth-integration,{project-full-name} Integrations>> :: Instrumentation configuration, context propagation, and more.
<<appendix.adoc#appendix,Appendices>> :: Span definitions and configuration properties.

8
docs/src/main/java/org/springframework/cloud/sleuth/documentation/SpanEntry.java
View File

@@ -35,11 +35,13 @@ class SpanEntry implements Comparable<SpanEntry> {
final String description;
final String prefix;
final Collection<KeyValueEntry> tagKeys;
final Collection<KeyValueEntry> events;
SpanEntry(String name, String enclosingClass, String enumName, String description,
SpanEntry(String name, String enclosingClass, String enumName, String description, String prefix,
Collection<KeyValueEntry> tagKeys, Collection<KeyValueEntry> events) {
Assert.isTrue(StringUtils.hasText(name), "Span name must not be empty");
Assert.isTrue(StringUtils.hasText(description), "Span description must not be empty");
@@ -47,6 +49,7 @@ class SpanEntry implements Comparable<SpanEntry> {
this.enclosingClass = enclosingClass;
this.enumName = enumName;
this.description = description;
this.prefix = prefix;
this.tagKeys = tagKeys;
this.events = events;
}
@@ -89,6 +92,9 @@ class SpanEntry implements Comparable<SpanEntry> {
text.append(".");
}
text.append("\n\n").append("Fully qualified name of the enclosing class `").append(this.enclosingClass).append("`");
if (StringUtils.hasText(prefix)) {
text.append("\n\nIMPORTANT: All tags and events must be prefixed with `").append(this.prefix).append("` prefix!");
}
if (!tagKeys.isEmpty()) {
text.append("\n\n.Tag Keys\n|===\n|Name | Description\n").append(this.tagKeys.stream().map(KeyValueEntry::toString).collect(Collectors.joining("\n")))
.append("\n|===");

8
docs/src/main/java/org/springframework/cloud/sleuth/documentation/SpanSearchingFileVisitor.java
View File

@@ -99,6 +99,7 @@ class SpanSearchingFileVisitor extends SimpleFileVisitor<Path> {
}
String name = "";
String description = enumConstant.getJavaDoc().getText();
String prefix = "";
Collection<KeyValueEntry> tags = new TreeSet<>();
Collection<KeyValueEntry> events = new TreeSet<>();
for (MemberSource<EnumConstantSource.Body, ?> member : members) {
@@ -117,11 +118,12 @@ class SpanSearchingFileVisitor extends SimpleFileVisitor<Path> {
else if ("getEvents".equals(methodName)) {
events.addAll(keyValueEntries(myEnum, methodDeclaration, EventValue.class));
}
else {
return null;
else if ("prefix".equals(methodName)) {
prefix = readStringReturnValue(methodDeclaration);
}
}
return new SpanEntry(name, myEnum.getCanonicalName(), enumConstant.getName(), description, tags, events);
return new SpanEntry(name, myEnum.getCanonicalName(), enumConstant.getName(), description, prefix, tags,
events);
}
private Collection<KeyValueEntry> keyValueEntries(JavaEnumImpl myEnum, MethodDeclaration methodDeclaration,