Jaeger: Jaeger client for PHP

[yurishkuro]

OpenTracing API for PHP is available: https://github.com/opentracing/opentracing-php

[jcchavezs]

Finally we have https://github.com/opentracing/opentracing-php, shall we update the issue @yurishkuro ?

[black-adder]

Just FYI, we do have someone currently building out the php client: https://github.com/jukylin/jaeger-php

[otisg]

@jcchavezs are you referring to https://github.com/jcchavezs/jaeger-client-php ? From what I can tell, https://github.com/jukylin/jaeger-php is further along. Maybe joining forces with @jukylin would be better?

[jukylin]

It's good idea .jukylin/jaeger-php depend on opentracing/opentracing-php, and we can make it more better together.

[jcchavezs]

I believe this one is looking great: https://github.com/jonahgeorge/jaeger-client-php I am thinking on joining @jonahgeorge.

[lvht]

The opentracing/opentracing-php is far from stable. Even it has a 1.0.0-beta release, its latest master branch breaks the API.

So I suppose to only depend on it when it hits a 1.0.0 release.

[felixfbecker]

The opentracing/opentracing-php is far from stable.

And so is jaeger-php. There is no reason to not start developing the Jaeger implementation. It's easy to change the API.

[lvht]

@felixfbecker It's easy to change the API until you use them in production environment.

[felixfbecker]

If you use a version clearly documented as unstable in production that's your own risk and no reason to artificially slow down development progress.

[yurishkuro]

In https://github.com/jaegertracing/jaeger/issues/366#issuecomment-348703406 @lvht said:

would you like to accept the lvht/jaeger-php as the official PHP client of Jaeger?

I would like to hear from other interested parties. I myself don't have a strong opinion since we do not write applications in PHP at Uber.

[tylerchr]

We have quite a bit of duplicated work going on here (or parallel efforts, depending on your perspective):

• @yuklin is working on https://github.com/jukylin/jaeger-php
• @jcchavezs is working on https://github.com/jcchavezs/jaeger-client-php (forked from _jonahgeorge_)
• @jonahgeorge is working on https://github.com/jonahgeorge/jaeger-client-php
• I'm working on https://github.com/qualtrics/jaeger-client-php
• @lvht is working on https://github.com/lvht/jaeger-php (apparently forked from _juklin_)
• @allflame is working on https://github.com/code-tool/jaeger-client-php
• @korchasa is working on https://github.com/korchasa/jaeger-client-php (forked from _allflame_)

Each of these are in various states of feature completeness, stability, opentracing-php compatibility, PHP5/7 compatibility, production-readiness, and maintenance.

Rather than balance many separate projects with one owner each, I propose we make an effort to merge these all into one repo with many owners. This will produce a much higher-quality client than if we each go it alone. @jonahgeorge and I have previously discussed merging our efforts, so maybe that's a place to start. Barring any objections, I'd be happy to own facilitating that.

[jukylin]

It's interesting

[yurishkuro]

100% in favor of merging the efforts into an official repository under https://github.com/jaegertracing.

Might be useful to have a feature comparison among the existing implementations, pros/cons. The parent ticket #366 lists the common requirements for an official client lib.

[allflame]

@tylerchr first of all, I'm personally in favor of combining efforts into a single library.
However, when I was looking over for existing implementations I failed to find one that was well-enough built and used a stack-based approach to automatically define parent-child span relationship.

I'm not sure we can advise to use our library at this point since it lacks documentation and tests, but we are proud of API stability that we were able to achieve.

[felixfbecker]

Could you explain what you mean by stack-based approach? How would that work with concurrent programming or an event loop?

[yurishkuro]

I assume "stack-based" refers to some form of active span management, which is important but should be solved at the OT API level, just like it was in Java/Python. I think that concern is very different from actually having an official PHP client for Jaeger, even if it doesn't have active span management features yet (because official PHP OT API doesn't have them).

[allflame]

@felixfbecker you start a span - an active context is put on stack, you finish span - you pop the context from the stack. This was (our own) solution coming from requirement not to pass context from layer to layer in the application itself. This is discussed and "rationalized" in some go applications, but it's really different language where this is a general approach.
About concurrency and event-loops: of course, your tracer should be thread-safe in order to work properly there. This is also mentioned in Opentracing documentation. Since you can still inject context and basically clone your tracer in another thread, I don't think this is a concern until async/await support.
As for event loop - I specifically added a possibility to manually specify parent context.

@yurishkuro You are completely right. This was never thought to be an "official" implementation. It does follow the formal requirements and have all necessary (at least for my use-case) features

[tylerchr]

The stack abstraction doesn't work for concurrent or event-loop-based languages, but PHP isn't concurrent or event-based. As such, a stack does model the in-process lifecycle of a trace very neatly for PHP, in what I believe is a closed-form way. A "push" starts a new span (which is a child of the span on the top of the stack if one exists), and a "pop" finishes the top span on the stack. It also has the nice advantage of providing a way to identify all the unfinished spans and close them, in unusual cases like when the script ends without completing execution (usually because someone called die() or exit(); in such cases it's nice to not lose your whole trace because the root span never got finished).

We did the same thing at Qualtrics (see this gist for our basic approach), but our stack implementation is outside our jaeger-client-php implementation and just works on the opentracing-php API. This seemed ideal because it offered a nice separation of concerns, without forcing my stack implementation on all users of my jaeger-client-php package. To @yurishkuro's point, should some kind of "active span management" functionality be standardized for PHP, it'll be relatively easy for us to replace.

[jukylin]

I release to v2.0.0-beta https://github.com/jukylin/jaeger-php

[sgnrslv]

Hi there.

We've implemented Jaeger client as PHP extension.

Probably, there is a lack of compatibility with all OpenTracing API concepts, but the extension covers all our needs and proved itself in a production battle ;)

So feel free to give it a try.

[sagikazarmark]

An extension sounds like a great idea, however I'm afraid that in many cases it's simply not an option. It would be awesome though if there would be a userland implementation which could be installed as a fallback when the extension is not available.

Anyway: I haven't worked on a Jaeger PHP client (yet), but I'm willing to join the coordination effort if it brings us any closer to the solution. (Maybe it even helps that I'm not biased 😉 )

I briefly looked into the libraries listed by @tylerchr , they all seem to follow similar concepts. There are differences in quality and implementation of course.

I agree with @yurishkuro that the first step could be a feature comparison. I would also take a look at the concrete solutions as well.

I know some of you expressed support for one or another libraries, but personally I think the best thing to do at this point is to agree on some key concepts based on the above comparisons, and start building a new library under the official jaegertracing org, even if that means copying over a bunch of source code.

That way everyone can equally contribute to the effort, the current libraries stay intact and even when copying source code, we can review the pieces again one by one.

[isaachier]

I'd highly recommend the extension route if possible. We already have a C++ client and I've been working on a pure C client as well.

[isaachier]

@sagikazarmark what you do mean "would not be an option." A huge amount of PHP is implemented in terms of C extensions.

[sagikazarmark]

In many environments custom built PHP extensions are not allowed or not possible for whatever reasons.

[isaachier]

We could package it via pear or wtvr

[sagikazarmark]

I guess it's not a coincidence that many extensions have a userland implementation as well (protobuf, twig to name a few). I'm not arguing that an extension would be better for a number of reasons. But it doesn't suit everyone.

[isaachier]

I understand. We will see what the community produces and evaluate any clients for a pure PHP version.

[tylerchr]

I started working on a feature comparison at the end of last year and never published it. It hasn't been updated since December, but only jonahgeorge/jaeger-client-php and code-tool/jaeger-client-php seem to have had any serious development since then. Perhaps @jonahgeorge and @allflame can update it?

https://docs.google.com/spreadsheets/d/19OTyj63I3YfLa8h4KGsAvljvA_AZDkhSeXYkFlPbnjg/edit#gid=0

@sagikazarmark's suggestion that we align on a set of core principles and then collaborate on a new implementation seems wise. I do suspect that a lot of code from (or derived from) the current implementations will wind up there, but that's just fine if we maintain a consistent bar of quality and polish.

[sagikazarmark]

This is really nice!

[allflame]

@tylerchr Great idea!
So as for our implemnentation:

1. It does support PHP 5.6. Specifically, there is a separate branch 1.0.x with all features backported there - mainly as the consequence of semantic versioning.
2. Not sure what does "Configuration" stands for. We tend to configure everything with DI containers like this. There is no standalone class like Factory::fromConfig if that's what you're talking about (we do not like static calls)
3. I'm not sure why you included HTTP/UDP support here since this is a part of Thrift client library itself. We did write our own UDP one to suppress some error message and remove a lot of (from our point) complicated and unnecessary code. Message: I don't think this should be included in the table, maybe only as "Additional features"
4. We do have all the samplers that are listed under the opentracing.io "Sampling" section including
5. Const
6. Probabilistic
7. RateLimiting
8. Adaptive

Latter 2 require apc extension (I think there is no way around to use something even more lightweight if you running it like fpm/cgi/mod and not standalone like react/php-pm/swoole). This will result in a side effect of a minimum Y*X instead of X traces if you have Y installation of application and set adaptive sampler rate to X.
Of course we do not have the Remote sampler since I think it was not opensourced by Uber yet.
We will implement Baggage in the next future just to add to the supported features, it's just we don't use it.

P.S. We can also build a bridge package to comply with opentracing-php, if someone feels like that would be useful.

[dragoscirjan]

Hello! How's the status on this one? Did anyone complete anything?

[asp24]

Hello! How's the status on this one? Did anyone complete anything?

All packages in code-tool org which contains "jaeger" in the name -- stable and works for a long time in production. So from my point of view, it's completed

[dragoscirjan]

@asp24 I'm not sure I understand your answer. If there is an official PHP jaeger client, I'm not sure where I could find it (if not on this project page). Furthermore, I see both major developers from the discussion above @jukylin and @jonahgeorge continue to develop on their own.

So my question still stands.

[yurishkuro]

@dragoscirjan we have had a similar situation with the C# client, where a couple of different repositories existed implementing the client, but their authors agreed to join the efforts, which resulted in an official client under the jaegertracing org maintained by the original authors. Something similar needs to happen here; we as core maintainers cannot make the call on which project is a better fit to become official client lib (since none of the core maintainers work with PHP). The first step towards that would be a feature comparison matrix.

[jonahgeorge]

If we can get @jukylin's repo accepted into the jaegertracing org, I'm happy to sunset mine (and join forces)

[sergeyklay]

I'm agree with @jonahgeorge

[jpkrohling]

I added the topic of the PHP client to the next Jaeger Project Bi-Weekly meeting: http://bit.do/jaeger-call

Interested parties: please join the meeting, ideally with an agreement about which repo to accept. I'd suggest following @yurishkuro's advice in building a feature comparison matrix, perhaps including the 9 guideline items listed under https://github.com/jaegertracing/jaeger/issues/366 . I'm afraid none of the current maintainers have enough PHP skills to judge and pick one implementation over the other ones.

cc @yuklin @jcchavezs @jonahgeorge @tylerch @lvht @allflame @korchasa

[LPodolski]

jukylin's repo still does not support beta 5 of open tracing, https://github.com/jukylin/jaeger-php/issues/21, jonahgeorge repo is better in that aspect

[CpuID]

Was there a decision made on which implementation is likely to go official...?

[jpkrohling]

IIRC, nobody showed up at the meeting. I'm closing this issue, as there seems to be demand from users but no volunteers to organize the merge.

[jpkrohling]

Sorry, it was wrong to close this. We have similar issues for other languages tracked as part of #366 and the issues are kept open until a client is accepted.

[zzarbi]

Just poking around but it seems that @jukylin 's version make the most sense, we can always bring back support for beta 5 into it. Furthermore he's still really active in his repo since the last 3 years. With that said thank you everybody for working on a solution. @jpkrohling what would you recommend we do in order to move forward on topic?

[yurishkuro]

Can we get a sense of how many people / companies are using https://github.com/jukylin/jaeger-php ?

[zzarbi]

@yurishkuro How do you want to collect this information?

[yurishkuro]

Reply here, ideally stating name of your company, type of usage (dev, prod, etc.), # of apps/services where lib is deployed, traffic volume if possible.

[zzarbi]

Company Name: Thrive Market
Usage: Dev, but ideally prod when we have stable version
Number of Service in PHP: +3
Volume: Our main service in staging is about 500request/minute
Current status: Development

[jukylin]

I know some companies using https://github.com/jukylin/jaeger-php. Maybe I can ask them for help.

[pavlelee]

Company Name: uxin
Project Name: After sale、Part of uxin finance
Usage: prod
Number of Project in PHP: +10
Volume: 40~100rps/service

[jukylin]

Company Name: ETC
Project Name: all
Usage: prod
Number of Project in PHP: +100
Volume: 1k/s

[yurishkuro]

@jukylin just to confirm, are you interested in moving https://github.com/jukylin/jaeger-php to https://github.com/jaegertracing ?

[jukylin]

No problem

[yurishkuro]

Sounds good. I booked a few issues in the repo that need to be resolved before the move: https://github.com/jukylin/jaeger-php/issues/created_by/yurishkuro

[JonasVerhofste]

I don't think the other projects, see this previous comment, should be disregarded. Some of them have features the other one does not have, for example the transport options of the qualtrics-one. I don't know if the matrix mentioned earlier is up to date, can't see an edit-date, but it's probably a good idea to update it, both the requirements as well as the compliance of those requirements.

Also, not sure if there's been a decent effort in trying to merge (some of) the projects together and if the concerning devs are (still) up for it. Would be a shame to lose functionality provided by a project because of the adoption of another one, in my opinion.

cc @jukylin @jonahgeorge @qualtrics (@tylerchr) @code-tool (@allflame) (not sure if organisation-mentions work)

[zzarbi]

@JonasVerhofste From my perspective it doesn't really matter which project we start on as long as we start on a project. Once we have a starting point we can start merging features. My goal is to get an official package that I can use on production with a community behind it.

[JonasVerhofste]

@zzarbi I get where you're coming from, but it'd be pretty stupid to blindly merge one project and we'd afterwards have to port all the functions from another one, when the other way around would've been less work.

I'm not saying that's the case here, haven't had the time to take a thorough look at the projects yet, I just want to make sure the choice is thought through and we're not creating unnecessary work for anyone.

[zzarbi]

@JonasVerhofste 100% agree and I wish someone did that in 2017 before everybody started expending their own implementation. I've looked trough the implementation of https://github.com/jukylin/jaeger-php for a POC and I can tell you there is a lot to do and a lot to clean up. This decision can easily be undone once we have an official repo with some people backing it up.

[allflame]

As for usage:
Company name: Evoplay
Project name: hundreds of them
Usage: prod
Number of Services: 120+
Volume: Hard to estimate, sampling with 0.001, cleaning 2TB Elastic index every 2 days
I would say the packagist statistics can be taken into consideration as well

As for the libraries:
I've got a lot of questions why would we write our own when there was already 2 or 3 in place, and I think I answered them here as well:

• OOD - existing libraries (at least at the time being) suffered from multiple anti-patterns (static calls, interface segregation, encapsulation violations etc)
• There was no way to inject tracer without putting random tracer-related stuff within the application classes, methods etc like Lock::acquire() -> Lock::acquire($context) etc
• There were no integration with popular PHP frameworks

I wouldn't go so far as to suggest that our version is better and would advocate on that behalf.
But it's

• better for us and for some other people who apparently (according to packagist) are using it.
• not designed as a high-level language translator from Go/Java/Javascript version to PHP which is good and bad at the same time
• can be integrated into any application without messing with application-level interfaces

[JonasVerhofste]

I wish someone did that in 2017 before everybody started expending their own implementation

@zzarbi Well, no turning back time. We'll just have to do with what we have right now.

This decision can easily be undone once we have an official repo with some people backing it up.

What do you mean? I don't think undoing the adoption of one project to adopt another one is something that can easily be done, if that's what you mean.

I would say the packagist statistics can be taken into consideration as well

@allflame That's something to go on indeed, but the statistics are quite mixed imo. @jukylin's is starred most, but yours is downloaded more. That's exactly why I said to not to disregard the other ones and make a comparison matrix. Map all the features and see which one has the most support, as to make the transition from the different community libraries to the official library as seamless as possible.

@yurishkuro any opinions on the matter?

[zzarbi]

@JonasVerhofste For instance what @allflame is talking about, like lack of OOD in @jukylin's implementation is something that can be fixed. A lot of what we're talking about is based on preferences which is why I proposed to stick to the first implementation and then to address all the concern that can be addressed.

The only thing that I think would be hard to change is the choice between a PHP extension or pure PHP. Beside that there is always going to be something we can do better regardless of the decision we make first.

[yurishkuro]

@JonasVerhofste this issue has been in analysis paralysis for almost two years. I tend to agree with @zzarbi that at this point it's more important to _make the choice_ rather than _make the best choice_. Unfortunately, I have zero domain knowledge of PHP, and looks like the other core maintainers are in the same boat, so we cannot provide much architectural guidance. Organizationally, the key to success of a client library is having several knowledgeable and active maintainers, as well as active user base.

[tylerchr]

Agreed, it's past time for us to pick something and commit to it. Despite authoring one client, I'd much rather have _a_ standard version than see it be my own (which is far from the best one, anyway!). My sense is that each author has an implementation that serves their current needs, and has a lack of either time or interest in building it out further. But this isn't @yurishkuro's problem to solve.

Organizationally, the key to success of a client library is having several knowledgeable and active maintainers, as well as active user base.

For this reason I would really like to see @jukylin, @allflame, @jonahgeorge, and myself all stay involved behind one client. Would each of you be willing to spend time porting your implementations' unique features over to a chosen codebase and trying to use it in your environments? If so let's pick the one with the cleanest design and do that.

A couple things I like from each of the others:

• jukylin/jaeger-php looks like the most feature-rich and actively developed.
• code-tool/jaeger-client-php seems to be the most idiomatic PHP and has the cleanest repository layout, to my eye. It also has the most Packagist downloads for what that's worth.
• jonahgeorge/jaeger-client-php is built against the most recent OpenTracing API (1.0.0-beta5) and is the only one of these with a CI pipeline.

Given just this 20-minute exercise, I think I'd be most inclined to take the @allflame's and start bringing things over from the others. Thoughts?

Flushing out the comparison sheet may or may not be helpful in assessing the relative merits. In any case I've opened it up for public edits if that's an exercise someone wants to undertake.

[tylerchr]

@yurishkuro Would OpenTelemetry affect this thinking at all? One potential solution is just to leave all our jaeger-client-php clients behind and join up on an OpenTelemetry client instead. It may still be too early for that though.

[yurishkuro]

@yurishkuro Would OpenTelemetry affect this thinking at all?

Yes, that is another option. In the longer term we're open to abandoning native Jaeger clients in all languages and fully switching to support OpenTelemetry default implementations (provided that we can get feature parity with Jaeger clients). I don't think this would happen for at least a year for the most used Jaeger clients (essentially the current official ones), but since we don't have an official one for PHP we can go directly to OpenTelemetry.

[zzarbi]

If we're planning to move to OpenTelemetry later, I think it would still makes sense to pick any of the current implementation. I picked @jukylin's only because it was the first one and so many other implementation forked it as well. I did not picked it based on implementation, features, coding style because I believe it can be address with some help.

[zzarbi]

FYI as pointed out earlier in this thread by @allflame, his repo has no documentation. I've been going thought his bridge implementation for Symfony and I don't think we would be able to help adding the documentation at first. Regarding @jonahgeorge his implementation requires php 7.3 or PECL/hrtime.

[jonahgeorge]

As an aside, I’m all for supporting the OpenTelemetry client

[MartijnZuijd]

is the effort to come to a single solution/combined effort still ongoing?

[andypost]

Expect it more tricky now in a light of coming PHP 8.0

[zzarbi]

I think you would have better luck overthere https://github.com/open-telemetry/opentelemetry-php

[jpkrohling]

I for one encourage you all to collaborate on OpenTelemetry's client!

[jpkrohling]

I'm closing this, as I don't think we'll progress with a client for PHP. If you disagree, leave a comment and I'll reopen.