Better user notification of deprecated flags and default changes

[esnible]

Requirement - what kind of business use case are you trying to solve?

It is not obvious to people consuming that all-in-one image when CLI flags are deprecated or defaults are changed.

The Istio project was using docker.io/jaegertracing/all-in-one:1.20. When I switched to 1.22, it stoped working.

The major problem was that Istio's Jaeger config sample was setting COLLECTOR_ZIPKIN_HTTP_PORT. In 1.22 the setting COLLECTOR_ZIPKIN_HOST_PORT must be used instead. It took longer than it should have to fix.

Problem - what in Jaeger blocks you from solving the requirement?

Jaeger seemed to be working, but tracing were not appearing in the UI because Jaeger was not listening to 9411 and not seeing the Zipkin-style traces Istio was sending.

My troubleshooting was made more difficult because I was testing Jaeger both with the web UI and grpcurl command line. Another change in 1.22 was to change the gRPC port and eliminate the mux.. The behavior observed by grpcurl was that queries timed out.

Proposal - what do you suggest to solve the problem or improve the existing situation?

• Log, at WARNING level, the use of deprecated CLI flags, in the all-in-one image.
• Log, at ERROR level, the use of removed Viper environment variables, in the all-in-one image. This is important. If the user is using the removed CLI flags, using a bad one can fail with a message to stdout and a crash loop. If the user is using removed environment variables, the behavior should be the same. With Viper is isn't.

For the gRPC timeout, probably the HTTP/gRPC mux should have stayed around a bit longer and every gRPC to the previous gRPC port should return UNIMPLEMENTED with a message to move to the new port.

It might also be worthwhile to log info messages such as "Starting GRPC on NEW DEFAULT PORT 16685" when defaults change, to make it more obvious.

Any open questions to address

The related Istio PR is https://github.com/istio/istio/pull/32681

I realize I should have read the release notes for Jaeger. What I ended up doing is capturing the logs from 1.20 and 1.22, removing their timestamps, and diffing them. Only a few lines were different. Anything that makes default behavior changes in log output more obvious is a good thing.

[yurishkuro]

Thank you for feedback. I think one thing we can definitely do is to extend the deprecation policy to require more time, e.g. 6m instead of 3m (or even 1yr), especially considering that we're not making new releases as often as in the past.

I agree that when flags are deprecated, we should be logging warnings when old flags are used. I think we did have some logs, but perhaps not consistently, it should be a mandatory part of deprecation policy.