elastic / apm-agent-php

Elastic APM PHP Agent

Elastic APM Agent for PHP

This is the official PHP agent for Elastic APM.

The PHP agent enables you to trace the execution of operations in your application, sending performance metrics and errors to the Elastic APM server.

☑️ We'd love to get information about your setup to help us with prioritizing framework support – please take a minute to fill out our survey.

If you have any feedback or questions, please post them at the Discuss forum.

Usage

This agent is a PHP extension that must be installed in your PHP environment.

See the documentation for setup and configuration details.

Contributing

See contributing documentation.

License

Elastic APM PHP Agent is licensed under Apache License, Version 2.0

apm-agent-php's Issues

Release Agent API as a composer package

This is regarding the requirements to be able to release a version for the apm-agent-php.

Requirements

• Easy to release
• CI should be orchestrator
• Sensitive credentials should be stored in Vault
• Release to https://packagist.org/
• One script to be able to release independently of the CI, so if required it should be possible to release locally. composer with packagist.org
• Tag event-based, when a particular tag release is created then the automation should do the same stages as done with PRs/Branches in addition to the release.

Actions

• Release automation with composer
• Create user in packagist and store credentials in vault
• Write down the release process in its RELEASING.md file
• Automate the process in the pipeine

Prerequisites

• The master build pipeline should be stable.

Questions

• Does packagist support snapshot releases? In other words, if we would like to potentially publish the binary for every PR, is that something we can achieve with that service? We already have in place artifactory, so I could ask if they support the PHP central repo. This is required for the ongoing iniative of moving to CD.

Use monotonic clock to measure relative duration

Follow up issue for #26 (comment)

We would like to make sure duration measured by the agent doesn't become negative if system clock is moved backwards.

Configuration options: ENABLED + RECORDING

The expected behavior is described in elastic/apm#92 (comment)

Configuration option: TRANSACTION_MAX_SPANS

Derived from elastic/apm#148

cgroup-based metrics

Derived from elastic/apm#291

Document how to deploy/use PHP Agent

• Update links to agent docs from other locations
  • APM Overview docs such as https://www.elastic.co/guide/en/apm/get-started/current/metadata.html
  • Kibana's APM \ Setup Instructions

Discover service name automatically

As step 1 we should define what is expected result for each use case (where use cases can be grouped by used web framework - WordPress, Laravel, etc.)

Consider when we can discover service name automatically:

• Investigate if developers already provide this information to some frameworks (Laravel, etc.)
• Investigate if we can extract service name from Apache/NGINX
• Investigate if we can extract service name from application location at the file system
• Investigate if there are other approaches

Implement OpenTracing API

Tasks

• Implement API
• Add tests
• Add documentation with examples

References

• https://github.com/opentracing/opentracing-php
• https://opentracing.io/tags/php/

Support filters to discard/modify events

• It should be possible to register filters via
  • Public API
  • Configuration for the case when developer prefers not to change applications source code
• Filter is called
  • Right after an event is created
  • Right after an event is ended (but before it's frozen and about to be added to the send-to-APM-server queue)
• Filter should be able
  • To modify the event
  • To discard the event
• Filter should be applied to all events - both the ones generated by automatic and manual instrumentation

For example .NET Agent's filter's related API

Automatically create transaction for each request

Collect system metrics (CPU and memory)

Add support for PHP user-land code auto-instrumentation

For example to support auto-instrumenting Guzzle HTTP client although particularly for Guzzle we might be okay without instrumenting PHP user-land code because IIUC Guzzle uses curl behind the scenes and curl is an extension and the agent already supports instrumenting methods/functions provided by PHP extensions.

Automatically create error events

Automatically create error events for the following use cases:

• Transaction/span exiting by exception
• PHP error (that is not reported as exception) occurring during transaction/span

Requires #57.

Configuration options: DISABLE_INSTRUMENTATIONS

DISABLE_INSTRUMENTATIONS configuration option be used to control which parts of auto-instrumentation are enabled.

Other agents:

• Java
• Node.js

Add opbeans-php

See Java and .NET examples.

Requires #1

Automatically create spans for outgoing HTTP calls

Add Error events to public API

• Add public API
• Tests
• Documentation

How to send error stack trace?

Is there any way that can be used to send an error stack trace. Usually, error traces are long enough.

Cannot make apm-agent-php

I was following the steps mentioned in THIS DOC. I was doing these in a docker container. But after I run the make command, it crashes. Am I doing anything wrong?
TIA.

Add logging

add a logging library, that logs to a file. The elasticapm.ini must provide the following configurations:

• log level, range: debug .. fatal. depending on the logging library
• log destination, path to log file

Set up CI pipeline to build/test PHP APM Agent

Dependencies table (Record sampling rate/weight on transactions and spans)

Derived from elastic/apm#270 and elastic/apm#307:

• Record a sampling rate/weight on transactions and spans
• Propagate sampling rate/weight via distributed tracing (by using tracestate)

Random Notice of Undefined variable: _SERVER

Hi!
I hope I'm not reporting bug "too soon" as there is no official release yet. I played with the agent today and I get a random Notice.

I run a Docker stack with:

• PHP 7.4.7
• PHP-FPM and Ngnix
• Debian based

I just run a simple index.php:

<?php

echo "Hello world\n";

And I get this notice:

Notice: Undefined variable: _SERVER in /apm-agent-php-master/src/ElasticApm/Impl/AutoInstrument/TransactionForExtensionRequest.php on line 84

The fact it's random bother me - I don't understand how to reproduce every-time.

When it happen the data are not send to the APM Server.

You can try with this branch: jolicode/docker-starter#104
As you can see I use the elastic_apm.bootstrap_php_part_file=/apm-agent-php-master/src/bootstrap_php_part.php configuration.

git clone [email protected]:jolicode/docker-starter.git
git checkout php-apm
echo '127.0.0.1 app.test' | sudo tee -a /etc/hosts
pipenv install
pipenv shell
inv start

Then go to https://app.test/

Thanks a lot for this agent, I'm looking forward being able to use it!

Package Agent as .apk for Alpine Linux distro

Package should:

• Install extension binary
• Install PHP part of the agent
• Update php.ini file(s) including setting elastic_apm.bootstrap_php_part_file

Public API to read/write properties of events

Public API should allow to read/write properties of events:

• Events include:
  • Transactions
  • Spans
  • Errors
• This API should be supported for both events automatically created by the agent and manually created by the user via the agent's public API

Configuration options: SERVICE_NAME and SERVICE_VERSION

For example Java agent documentation: SERVICE_NAME and SERVICE_VERSION.

Mark `elasticapm.enabled` as not modifiable

Fill in metadata.system.kubernetes

Agent should fill in metadata.system.kubernetes.

• Intake API schema
• Implementation details
• Implement elastic/apm#344

Automatically create spans for DB operations

Add the support of socket connection using libcurl

Since we want to support socket connection for communicate with APM server, we need to add it to CURL connection.
We want to give the possibility to specify a URL string in elasticapm.host using http: (or https:) and a socket connection using unix: prefix.

Agent deployment using PECL

• Implementation
• Documentation

Refactor the random generation of trace_id and transaction_id

We need to refactor the random generation of trace_id and transaction_id. Right now, we are using this code for transaction_id:

memset(GA(transaction_id), 0, sizeof(char)*17);
for (int i=0, j=0; i<8; i++, j+=2) {
    sprintf(GA(transaction_id)+j, "%02x", php_mt_rand() % 256);
}

and this for trace_id:

memset(GA(trace_id), 0, sizeof(char)*33);
for (int i=0, j=0; i<16; i++, j+=2) {
    sprintf(GA(trace_id)+j, "%02x", php_mt_rand() % 256);
}

We can continue to use php_mt_rand() that is 4x faster than libc rand() and it is automatically seed. We would like to have a funcion for generating x random bytes in hex format.

Do not display secret token in phpinfo()

Either obfuscate or hide the elasticapm.secret_token from the php info output.

Package Agent as .rpm for RHEL/Centos, Fedora, etc. Linux distros

Package should:

• Install extension binary
• Install PHP part of the agent
• Update php.ini file(s) including setting elastic_apm.bootstrap_php_part_file

Prepare README.md for making the repo public

• Move the Note on status to the top
• Rename copyright to license
• Remove authors
• Add contributing.md

Collect cloud identification metadata

Derived from elastic/apm#256
See also elastic/apm#289
See also #921
See also #1053

Need to complete OSS Process/legal stuff

have a look here

Follow up issue - Add automatic verification for copyright header in source files #361

Testing Environment

create a dockerized testing environment, that:

• spins up an image with nginx:latest, php-fpm:latest, php7.3.x and sample wordpress
• a supporting database for required storage

Further steps:

• install all extensions and setup env
• manipulate wordpress to throw an exception on random values
• use hey to simulate load

Configuration option: TRANSACTION_IGNORE_URLS

Derived from elastic/apm#144

• Implement wildcard matching
  • Automated tests should verify at least test cases from json-specs (local copy should be at tests/APM_Agents_shared/json-specs)

Support Distributed Tracing

Provide support for distributed tracing, in case an http request with the header TRACEPARENT or ELASTIC-APM-TRACEPARENT is issued, use the value that must comply W3C trace context, example.

• Implement
• Documentation (including on how manually pass tracing context)

Error to compile on php:5.6.40-fpm-alpine3.8

Hello guys,

I'm trying to install the apm agent using the php:5.6.40-fpm-alpine3.8 docker image. However, I got the error:

/bin/bash /home/apm-agent/apm/src/ext/libtool --mode=compile cc  -I. -I/home/apm-agent/apm/src/ext -DPHP_ATOM_INC -I/home/apm-agent/apm/src/ext/include -I/home/apm-agent/apm/src/ext/main -I/home/apm-agent/apm/src/ext -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib  -DHAVE_CONFIG_H  -g -O2   -c /home/apm-agent/apm/src/ext/ConfigManager.c -o ConfigManager.lo 
mkdir .libs
 cc -I. -I/home/apm-agent/apm/src/ext -DPHP_ATOM_INC -I/home/apm-agent/apm/src/ext/include -I/home/apm-agent/apm/src/ext/main -I/home/apm-agent/apm/src/ext -I/usr/local/include/php -I/usr/local/include/php/main -I/usr/local/include/php/TSRM -I/usr/local/include/php/Zend -I/usr/local/include/php/ext -I/usr/local/include/php/ext/date/lib -DHAVE_CONFIG_H -g -O2 -c /home/apm-agent/apm/src/ext/ConfigManager.c  -fPIC -DPIC -o .libs/ConfigManager.o
In file included from /home/apm-agent/apm/src/ext/elastic_apm_alloc.h:20:0,
                 from /home/apm-agent/apm/src/ext/ConfigManager.c:25:
/home/apm-agent/apm/src/ext/platform.h:16:38: fatal error: execinfo.h: No such file or directory
 #   include <execinfo.h> // backtrace
                                      ^
compilation terminated.
make: *** [Makefile:181: ConfigManager.lo] Error 1

The command I used to install is:

RUN mkdir -p /home/apm-agent && \
    cd /home/apm-agent && \
    git clone https://github.com/elastic/apm-agent-php.git apm && \
    cd apm/src/ext && \
    /usr/local/bin/phpize && ./configure --enable-elastic_apm && \
    make clean && make

Any Idea?
All the best.

Public API to manually create transactions, spans and errors

Manual Instrumentation

Provide the PHP classes reflecting the APM event specs for users to manually instrument their codebase, leveraging the c-ext as a sender. These events are passed to the c-ext with a method e.g. elasticapm_send_event(string $event) and the c-ext takes care of the sending to the APM server.

CI build should fail if 'make test' fails with segmentation fault

It seems that 'make test' step of CI build marked as successful even when it actually fails with Segmentation fault. For example: PR elastic/apm-agent-php#26 build 5 is green even though Segmentation fault was fixed only in build 6.

Prevent Request too large errors

In using philkra/elastic-apm-php-agent to instrument my applications, I have run into some size limits in the post to apm. I just thought I would share the conditions that have caused this error, and how I have mitigated them. It would be useful to have this be handled, or have methods to let me handle it.

1. Very large SQL queries. I put a maxlength on the sql query that gets sent in the span (truncate anything over).
2. Too many queries / spans. (Batch jobs that run for a long time and can build up quite a lot of spans) In my own auto instrumenting functions I set a flag that would let me temporarily turn off the auto instrumenting to avoid this issue. (i.e.: create span for large loop, turn off auto instrument, run large loop, turn it back on, end span)

I know the njson format works well with streaming events as they come, but is this something where it might want to chunk the events if the size is large?

[docs] Add documentation template

Use the (slightly outdated) Agent documentation template to add a template for PHP documentation. We can leave this disconnected from the doc build for now.

Jenkins CI is broken

builds fail when notified to GitHub

[2020-01-17T08:33:37.070Z] [Elastic] Done with build 20200117083133-7E51CD7A.
[2020-01-17T08:33:37.380Z] 
[2020-01-17T08:33:37.380Z] Could not update commit status, please check if your scan credentials belong to a member of the organization or a collaborator of the repository and repo:status scope is selected
[2020-01-17T08:33:37.380Z] 
[2020-01-17T08:33:37.380Z] 
[2020-01-17T08:33:37.380Z] GitHub has been notified of this commit’s build result
[2020-01-17T08:33:37.380Z] 
[2020-01-17T08:33:37.380Z] java.io.FileNotFoundException: https://api.github.com/repos/elastic/ecs-logging-php/statuses/27f2ed0532a0a6cb8d52eb499bcba24ba6e20028
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1896)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1498)
[2020-01-17T08:33:37.380Z] 	at java.net.HttpURLConnection.getResponseCode(HttpURLConnection.java:480)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.https.HttpsURLConnectionImpl.getResponseCode(HttpsURLConnectionImpl.java:352)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester.parse(Requester.java:615)
[2020-01-17T08:33:37.380Z] Caused: java.io.FileNotFoundException: https://api.github.com/repos/elastic/ecs-logging-php/statuses/27f2ed0532a0a6cb8d52eb499bcba24ba6e20028
[2020-01-17T08:33:37.380Z] 	at sun.reflect.GeneratedConstructorAccessor1565.newInstance(Unknown Source)
[2020-01-17T08:33:37.380Z] 	at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
[2020-01-17T08:33:37.380Z] 	at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection$10.run(HttpURLConnection.java:1950)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection$10.run(HttpURLConnection.java:1945)
[2020-01-17T08:33:37.380Z] 	at java.security.AccessController.doPrivileged(Native Method)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection.getChainedException(HttpURLConnection.java:1944)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection.getInputStream0(HttpURLConnection.java:1514)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.http.HttpURLConnection.getInputStream(HttpURLConnection.java:1498)
[2020-01-17T08:33:37.380Z] 	at sun.net.www.protocol.https.HttpsURLConnectionImpl.getInputStream(HttpsURLConnectionImpl.java:268)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester.parse(Requester.java:625)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester.parse(Requester.java:607)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester._to(Requester.java:285)
[2020-01-17T08:33:37.380Z] Caused: org.kohsuke.github.GHFileNotFoundException: {"message":"Not Found","documentation_url":"https://developer.github.com/v3/repos/statuses/#create-a-status"}
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester.handleApiError(Requester.java:699)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester._to(Requester.java:306)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.Requester.to(Requester.java:247)
[2020-01-17T08:33:37.380Z] 	at org.kohsuke.github.GHRepository.createCommitStatus(GHRepository.java:1104)
[2020-01-17T08:33:37.380Z] 	at org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep$Execution.run(GitHubStatusNotificationStep.java:381)
[2020-01-17T08:33:37.380Z] 	at org.jenkinsci.plugins.pipeline.githubstatusnotification.GitHubStatusNotificationStep$Execution.run(GitHubStatusNotificationStep.java:355)
[2020-01-17T08:33:37.380Z] 	at org.jenkinsci.plugins.workflow.steps.AbstractSynchronousNonBlockingStepExecution$1$1.call(AbstractSynchronousNonBlockingStepExecution.java:47)
[2020-01-17T08:33:37.380Z] 	at hudson.security.ACL.impersonate(ACL.java:290)
[2020-01-17T08:33:37.380Z] 	at org.jenkinsci.plugins.workflow.steps.AbstractSynchronousNonBlockingStepExecution$1.run(AbstractSynchronousNonBlockingStepExecution.java:44)
[2020-01-17T08:33:37.380Z] 	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511)
[2020-01-17T08:33:37.380Z] 	at java.util.concurrent.FutureTask.run(FutureTask.java:266)
[2020-01-17T08:33:37.380Z] 	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
[2020-01-17T08:33:37.380Z] 	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
[2020-01-17T08:33:37.380Z] 	at java.lang.Thread.run(Thread.java:748)
[2020-01-17T08:33:37.380Z] Finished: FAILURE

The make test is broken

The make test is broken. We need to double check the configure the config.m4 file for testing.

Package Agent as .deb for Ubuntu, Debian, etc. Linux distros

Package should:

• Install extension binary
• Install PHP part of the agent
• Update php.ini file(s) including setting elastic_apm.bootstrap_php_part_file

Tasks

• PoC -> #79
• Define what the installation needs to do. -> #98
• Agree the folder layout. -> See #107
• Follow-up regarding functional testing and non-functional testing (installing, uninstalling, upgrading ...). See #100
• Support versioning for PRs that are unique and compatible with the package manager. See #108
• Create smoke tests to verify the package gets installed as expected.
• Confirm what data to be replaced in the package metadata.

Add support for auto-instrumentation + library-only deployment option

Enrico implemented POC for the approach based on AOP at https://github.com/elastic/apm-agent-php-library