Sleuth - Distributed Tracing
Support for distributed tracing of requests is enabled by including the following dependency in the WAR overlay:
1
2
3
4
5
<dependency>
<groupId>org.apereo.cas</groupId>
<artifactId>cas-server-support-sleuth</artifactId>
<version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-sleuth:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
imports {
mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
}
}
dependencies {
implementation "org.apereo.cas:cas-server-support-sleuth"
}
1
2
3
4
5
6
7
8
9
10
dependencies {
/*
The following platform references should be included automatically and are listed here for reference only.
implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
*/
implementation "org.apereo.cas:cas-server-support-sleuth"
}
For most users Sleuth should be invisible, and all interactions with external systems should be instrumented automatically.
Trace data is captured automatically and passed along to Zipkin, which helps gather timing data needed to troubleshoot latency problems.
The following settings and properties are available from the CAS configuration catalog:
spring.sleuth.async.configurer.enabled=true
|
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
|
spring.sleuth.baggage.correlation-enabled=true
Enables correlating the baggage context with logging contexts.
|
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=
List of fields that should automatically become tags.
|
spring.sleuth.batch.enabled=true
|
spring.sleuth.cassandra.enabled=true
|
spring.sleuth.circuitbreaker.enabled=true
Enable Spring Cloud CircuitBreaker instrumentation.
|
spring.sleuth.config.server.enabled=true
|
spring.sleuth.deployer.enabled=true
|
spring.sleuth.deployer.status-poll-delay=500
|
spring.sleuth.enabled=true
|
spring.sleuth.feign.enabled=true
Enable span information propagation when using Feign.
|
spring.sleuth.feign.processor.enabled=true
Enable post processor that wraps Feign Context in its tracing representations. How can I configure this property?
|
spring.sleuth.function.enabled=true
Enable instrumenting of Spring Cloud Function and Spring Cloud Function based projects (e.g. Spring Cloud Stream). How can I configure this property?
|
spring.sleuth.grpc.enabled=true
|
spring.sleuth.http.enabled=true
Enables HTTP support.
|
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
|
spring.sleuth.jdbc.datasource-proxy.enabled=true
Should the datasource-proxy tracing be enabled?
|
spring.sleuth.jdbc.datasource-proxy.json-format=false
Use json output for logging query. @see ProxyDataSourceBuilder#asJson()
|
spring.sleuth.jdbc.datasource-proxy.logging=
Logging to use for logging queries.
|
spring.sleuth.jdbc.datasource-proxy.multiline=true
Use multiline output for logging query. @see ProxyDataSourceBuilder#multiline()
|
spring.sleuth.jdbc.datasource-proxy.query.enable-logging=false
Enable logging all queries to the log.
|
spring.sleuth.jdbc.datasource-proxy.query.log-level=DEBUG
Severity of query logger.
|
spring.sleuth.jdbc.datasource-proxy.query.logger-name=
Name of query logger.
|
spring.sleuth.jdbc.datasource-proxy.slow-query.enable-logging=false
Enable logging slow queries to the log.
|
spring.sleuth.jdbc.datasource-proxy.slow-query.log-level=WARN
Severity of slow query logger.
|
spring.sleuth.jdbc.datasource-proxy.slow-query.logger-name=
Name of slow query logger.
|
spring.sleuth.jdbc.datasource-proxy.slow-query.threshold=300
Number of seconds to consider query as slow.
|
spring.sleuth.jdbc.enabled=true
Enables JDBC instrumentation.
|
spring.sleuth.jdbc.excluded-data-source-bean-names=
List of DataSource bean names that will not be decorated.
|
spring.sleuth.jdbc.includes=
Which types of tracing we would like to include.
|
spring.sleuth.jdbc.p6spy.custom-appender-class=
Class file to use (only with logging=custom). The class must implement
|
spring.sleuth.jdbc.p6spy.enable-logging=false
Enables logging JDBC events.
|
spring.sleuth.jdbc.p6spy.enabled=true
Should the p6spy tracing be enabled?
|
spring.sleuth.jdbc.p6spy.log-file=spy.log
Name of log file to use (only with logging=file).
|
spring.sleuth.jdbc.p6spy.log-filter.pattern=
Use regex pattern to filter log messages. Only matched messages will be logged.
|
spring.sleuth.jdbc.p6spy.log-format=
Custom log format.
|
spring.sleuth.jdbc.p6spy.logging=
Logging to use for logging queries.
|
spring.sleuth.jdbc.p6spy.multiline=true
Enables multiline output.
|
spring.sleuth.jdbc.p6spy.tracing.include-parameter-values=false
Report the effective sql string (with '?' replaced with real values) to tracing systems. NOTE this setting does not affect the logging message.
|
spring.sleuth.kafka.enabled=true
|
spring.sleuth.messaging.aspect.enabled=false
Should
|
spring.sleuth.messaging.enabled=false
Should messaging be turned on.
|
spring.sleuth.messaging.jms.enabled=true
Enable tracing of JMS.
|
spring.sleuth.messaging.jms.remote-service-name=jms
JMS remote service name.
|
spring.sleuth.messaging.kafka.enabled=true
Enable tracing of Kafka.
|
spring.sleuth.messaging.kafka.mapper.enabled=true
|
spring.sleuth.messaging.kafka.remote-service-name=kafka
Kafka remote service name.
|
spring.sleuth.messaging.kafka.streams.enabled=false
Should Kafka Streams be turned on.
|
spring.sleuth.messaging.rabbit.enabled=true
Enable tracing of RabbitMQ.
|
spring.sleuth.messaging.rabbit.remote-service-name=rabbitmq
Rabbit remote service name.
|
spring.sleuth.mongodb.enabled=true
|
spring.sleuth.mongodb.socket-address-span-customizer.enabled=false
|
spring.sleuth.opentracing.enabled=true
Enables OpenTracing support.
|
spring.sleuth.propagation.type=
Tracing context propagation types.
|
spring.sleuth.quartz.enabled=true
|
spring.sleuth.r2dbc.enabled=true
|
spring.sleuth.reactor.decorate-on-each=true
When true decorates on each operator, will be less performing, but logging will always contain the tracing entries in each operator. When false decorates on last operator, will be more performing, but logging might not always contain the tracing entries.
Deprecation status is |
spring.sleuth.reactor.enabled=true
When true enables instrumentation for reactor.
|
spring.sleuth.reactor.instrumentation-type=
|
spring.sleuth.redis.enabled=true
Enable span information propagation when using Redis.
|
spring.sleuth.redis.legacy.enabled=false
|
spring.sleuth.redis.remote-service-name=redis
Service name for the remote Redis endpoint.
|
spring.sleuth.rpc.enabled=true
|
spring.sleuth.rsocket.enabled=true
When true enables instrumentation for rsocket.
|
spring.sleuth.rxjava.schedulers.hook.enabled=true
Enable support for RxJava via RxJavaSchedulersHook.
|
spring.sleuth.rxjava.schedulers.ignoredthreads=HystrixMetricPoller^RxComputation.*$
Thread names for which spans will not be sampled.
|
spring.sleuth.sampler.probability=
Probability of requests that should be sampled. E.g. 1.0 - 100% requests should be sampled. The precision is whole-numbers only (i.e. there's no support for 0.1% of the traces).
|
spring.sleuth.sampler.rate=10
A rate per second can be a nice choice for low-traffic endpoints as it allows you surge protection. For example, you may never expect the endpoint to get more than 50 requests per second. If there was a sudden surge of traffic, to 5000 requests per second, you would still end up with 50 traces per second. Conversely, if you had a percentage, like 10%, the same surge would end up with 500 traces per second, possibly overloading your storage. Amazon X-Ray includes a rate-limited sampler (named Reservoir) for this purpose. Brave has taken the same approach via the
|
spring.sleuth.sampler.refresh.enabled=true
|
spring.sleuth.scheduled.enabled=true
Enable tracing for
|
spring.sleuth.scheduled.skip-pattern=
Pattern for the fully qualified name of a class that should be skipped.
|
spring.sleuth.session.enabled=true
|
spring.sleuth.span-filter.additional-span-name-patterns-to-ignore=
Additional list of span names to ignore. Will be appended to
|
spring.sleuth.span-filter.enabled=false
Will turn on the default Sleuth handler mechanism. Might ignore exporting of certain spans;
|
spring.sleuth.span-filter.span-name-patterns-to-skip=^catalogWatchTaskScheduler$
List of span names to ignore. They will not be sent to external systems.
|
spring.sleuth.supports-join=true
True means the tracing system supports sharing a span ID between a client and server.
|
spring.sleuth.task.enabled=true
|
spring.sleuth.trace-id128=false
When true, generate 128-bit trace IDs instead of 64-bit ones.
|
spring.sleuth.tracer.mode=
Set which tracer implementation should be picked.
|
spring.sleuth.tx.enabled=true
|
spring.sleuth.vault.enabled=true
|
spring.sleuth.web.additional-skip-pattern=
Additional pattern for URLs that should be skipped in tracing. This will be appended to the
|
spring.sleuth.web.client.enabled=true
Enable interceptor injecting into
|
spring.sleuth.web.client.skip-pattern=
Pattern for URLs that should be skipped in client side tracing.
|
spring.sleuth.web.enabled=true
When true enables instrumentation for web applications.
|
spring.sleuth.web.filter-order=0
Order in which the tracing filters should be registered.
|
spring.sleuth.web.ignore-auto-configured-skip-patterns=false
If set to true, auto-configured skip patterns will be ignored.
|
spring.sleuth.web.servlet.enabled=true
Enable servlet instrumentation.
|
spring.sleuth.web.skip-pattern=/api-docs.*|/swagger.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|/hystrix.stream
Pattern for URLs that should be skipped in tracing.
|
spring.sleuth.web.tomcat.enabled=true
|
spring.sleuth.web.webclient.enabled=true
|
spring.zipkin.activemq.message-max-bytes=100000
Maximum number of bytes for a given message with spans sent to Zipkin over ActiveMQ. How can I configure this property?
|
spring.zipkin.activemq.queue=zipkin
|
spring.zipkin.api-path=
The API path to append to baseUrl (above) as suffix. This applies if you use other monitoring tools, such as New Relic. The trace API doesn't need the API path, so you can set it to blank ("") in the configuration.
|
spring.zipkin.base-url=http://localhost:9411/
URL of the zipkin query server instance. You can also provide the service id of the Zipkin server if Zipkin's registered in service discovery (e.g. https://zipkinserver/).
|
spring.zipkin.check-timeout=1000
Timeout in millis for the check for Zipkin availability.
|
spring.zipkin.compression.enabled=false
|
spring.zipkin.discovery-client-enabled=
If set to
|
spring.zipkin.enabled=true
Enables sending spans to Zipkin.
|
spring.zipkin.encoder=
Encoding type of spans sent to Zipkin. Set to
|
spring.zipkin.kafka.topic=zipkin
|
spring.zipkin.locator.discovery.enabled=false
Enabling of locating the host name via service discovery.
|
spring.zipkin.message-timeout=1
Timeout in seconds before pending spans will be sent in batches to Zipkin.
|
spring.zipkin.queued-max-spans=1000
Maximum backlog of spans reported vs sent.
|
spring.zipkin.rabbitmq.addresses=
|
spring.zipkin.rabbitmq.queue=zipkin
|
spring.zipkin.sender.type=
Means of sending spans to Zipkin.
|
spring.zipkin.service.name=
The name of the service, from which the Span was sent via HTTP, that should appear in Zipkin.
|
Configuration Metadata
The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.
Be Selective
This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.
YAGNI
Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.
Naming Convention
Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all
forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where
this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those
that might be presented to the system via an external library or framework such as Spring Boot, etc.
When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.
The only possible exception to this rule is when naming actuator endpoints; The name of the
actuator endpoints (i.e. ssoSessions) MUST remain in camelCase mode.
Settings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided
to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with
the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition
or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the
way you intend.
Validation
Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be
recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system
property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled
via Configuration Metadata and property migrations applied automatically on
startup by Spring Boot and family.
Indexed Settings
CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be
incremented by the adopter to allow for distinct multiple configuration blocks.
Troubleshooting
To enable additional logging, modify the logging configuration file to add the following:
1
2
3
4
<Logger name="org.springframework.cloud" level="debug" additivity="false">
<AppenderRef ref="casConsole"/>
<AppenderRef ref="casFile"/>
</Logger>