[Bug]: Missing php classes stubs

[zbigniew-malcherczyk-tg]

Bug report

There are a few missing stubs for version 1.4.2

• https://github.com/DataDog/dd-trace-php/blob/master/src/DDTrace/Span.php
• https://github.com/DataDog/dd-trace-php/blob/master/src/DDTrace/SpanContext.php

Please. It's so hard to work with dd-trace library and extension. It's really sad how hard it is to install the extension, to maintain anything that depends on this lib. No to mention that release is 1GB...

PHP version

8.2.25

Tracer or profiler version

1.4.2

Installed extensions

No response

Output of phpinfo()

No response

Upgrading from

No response

[bwoebi]

Hey @zbigniew-malcherczyk-tg,

I'm a bit confused here what you would like to see here. The *.stub.php files are for functions exposed by the extension, not the PHP source files shipped alongside it.

I'd like to understand the usecase / workflow for this? For integration in the IDE, I just pull it via composer and it sees the stub files as well as all files in src/.

[bwoebi]

I'd like though, to understand, why installing the extension is hard? I thought just downloading and executing php datadog-setup.php would be really easy.
But maybe that's not the case?

About the size of the full artifact (containing all php versions), we've been annoyed too. I suppose the easiest way is to split this up into more individual files...

[bwoebi]

Overall, we're also willing to hear what makes it hard to work with dd-trace-php. In fact, we mostly hear from our users when something is actually broken, but merely "hard to work with" is nothing I get to hear often. Feedback is important and most welcome too.

[zbigniew-malcherczyk-tg]

Hi! @bwoebi Let's start from the files and stubs. The OpenTelemetry is relatively new feature for PHP and datadog, so I cannot tell if that would solve anything for us. Our usecase is that you just cannot enable tracing for everything to get more detailed info we have to provide spans and tags semi-manual. For that we use and more

use DDTrace\Contracts\Span;
use DDTrace\GlobalTracer;
use DDTrace\Http\Urls;
use DDTrace\Tag;
use DDTrace\Contracts\Span;

So we could call it internal tooling-ish. Now the stubs are mostly important with two cases IDE and phpstan. It is a great PITA that the stubs don't consists of other elements. Those listed above are part of extension, but are not marked as internal, therefore they should usable.

[zbigniew-malcherczyk-tg]

Another thing is partially what you mentioned with the package consisting all of the versions. That is very heavy on network and time-consuming. Example. I have to wait just for the datadog download about 15 minutes. That is with super nice internet (mostly the time comes from github API limits).

So there are a couple of ways now to install the extension.

1. The release is downloaded and installed by apt/dpkg and other package managers. This requires download from github and it takes a significant amount of time.
2. The pecl install. This one is quite bad as well, because the dev dependencies are required for the installation. That is pecl characteristic and we all know it's not perfect. Quite legacy.
3. These datadog-setup.php file is not tested by me, but I would start with a simple question. How do I get this file in the first place for my Dockerfile? From the github repo? I would need to download it. Copy and paste it? I would need to maintain it. Yet it does download the same release as the first solution.

Like you can see something quite simple is either too complicated or waaay bigger. Probably if I were to tell you that you need to download 1GB, but you need just like 50MB from it you would call it strange 😢 We could save a lot of trees if the release file was matrix'ed by not only platform/arch but PHP version as well. Easy like that.

[bwoebi]

Thanks @zbigniew-malcherczyk-tg,

We quickly tried generating stubs in #2933. The resulting src/ddtrace_php_api.stubs.php contains all stubs for the PHP code, minus the extension stubs. I wonder, at that point, whether it would be preferable to have a single stub file instead of 4? (merging that one, ext/ddtrace.stub.php and ext/hook/uhook.stub.php and ext/hook/uhook_attributes.stub.php?) Also, do you wish to see that as a release artifact or rather just in the repository?

[zbigniew-malcherczyk-tg]

Thank you for the stub's. The ideal scenario and usecase would be a separate composer package like phpstan-ddtrace or something, but a release artifact should be enough. Single stub file would improve the experience.

[bwoebi]

Sounds good, we'll add some logic to compile a big stub file together and add it as artifact.
A composer package is probably quite a bit more annoying as you cannot have more than one per github repository... (AFAIK?)

[zbigniew-malcherczyk-tg]

Yea. packageist mostly supports single package single repository scenarios 😢

[bwoebi]

Release artifacts now have a datadog-tracer.stubs.php file. For release 1.5.0 that is at https://github.com/DataDog/dd-trace-php/releases/download/1.5.0/datadog-tracer.stubs.php.

[morrisonlevi]

These datadog-setup.php file is not tested by me, but I would start with a simple question. How do I get this file in the first place for my Dockerfile? From the github repo? I would need to download it. Copy and paste it? I would need to maintain it. Yet it does download the same release as the first solution.

To address these related things about datadog-setup.php:

1. Yes, you download datadog-setup.php from the repository for the given release e.g. https://github.com/DataDog/dd-trace-php/releases/download/1.5.0/datadog-setup.php. This is a small download.
2. The datadog-setup.php script does not do the same stuff as the apk/deb/etc files. It is intended to work on far more deployments (which is partly why it was created, each one of those package types has restrictions that make it not work for some customers).
3. The datadog-setup.php script then downloads artifacts based on PHP version and platform. In the past, this additional download was quite large, but as of 1.5 it's small again. For a single PHP version (the most common case), the download is roughly 40 MiB.

The datadog-setup.php script usage will often look like this (slightly modified from Getting Started):

# APM only
php datadog-setup.php --php-bin=all

# APM + Profiling
php datadog-setup.php --php-bin=all --enable-profiling

# APM + ASM
php datadog-setup.php --php-bin=all --enable-appsec

# Full installation: APM + ASM + Profiling
php datadog-setup.php --php-bin=all --enable-appsec --enable-profiling

You can also use it to set INI settings, which is my preferred way to configure things (slightly modified from the profiler's Installation Docs):

php datadog-setup.php config set --php-bin=all \
  -d datadog.service="app-name" \
  -d datadog.env="prod" \
  -d datadog.version="1.3.2"

If you want to env vars at runtime (like in docker or such) you can also do things like this, it's a little known feature of PHP INI settings:

php datadog-setup.php config set --php-bin=all \
  -d datadog.service="\$DD_SERVICE" \
  -d datadog.env="\$DD_ENV" \
  -d datadog.version="\$DD_VERSION"