From ebc9ac1955c2a884faaee23b7c7adcc6606e891a Mon Sep 17 00:00:00 2001 From: Maksym Date: Sat, 20 May 2023 19:08:08 +0300 Subject: [PATCH] Added `datadog` extension (#442) Co-authored-by: Maksym Odanets --- Readme.md | 99 ++++++++++++++++++++------------------ docs/datadog.md | 86 +++++++++++++++++++++++++++++++++ layers/datadog/Dockerfile | 33 +++++++++++++ layers/datadog/config.json | 7 +++ layers/datadog/test.php | 8 +++ 5 files changed, 186 insertions(+), 47 deletions(-) create mode 100644 docs/datadog.md create mode 100644 layers/datadog/Dockerfile create mode 100644 layers/datadog/config.json create mode 100644 layers/datadog/test.php diff --git a/Readme.md b/Readme.md index 117d1d8e..dbe9d0e5 100644 --- a/Readme.md +++ b/Readme.md @@ -42,53 +42,54 @@ functions: ### Available layers -| Name | Serverless config (php 8.1) | -|:-------------------|:--------------------------------------| -| AMQP | `${bref-extra:amqp-php-81}` | -| Blackfire | `${bref-extra:blackfire-php-81}` | -| Bsdiff | `${bref-extra:bsdiff-php-81}` | -| Calendar | `${bref-extra:calendar-php-81}` | -| Cassandra | `${bref-extra:cassandra-php-81}` | -| Decimal | `${bref-extra:decimal-php-81}` | -| DS | `${bref-extra:ds-php-81}` | -| Elastic APM | `${bref-extra:elastic-apm-php-81}` | -| GD | `${bref-extra:gd-php-81}` | -| gnupg | `${bref-extra:gnupg-php-81}` | -| GMP | `${bref-extra:gmp-php-81}` | -| gRPC | `${bref-extra:grpc-php-81}` | -| Igbinary | `${bref-extra:igbinary-php-81}` | -| Imagick | `${bref-extra:imagick-php-81}` | -| IMAP | `${bref-extra:imap-php-81}` | -| LDAP | `${bref-extra:ldap-php-81}` | -| Mailparse | `${bref-extra:mailparse-php-81}` | -| MaxMind DB | `${bref-extra:maxminddb-php-81}` | -| Memcache | `${bref-extra:memcache-php-81}` | -| Memcached | `${bref-extra:memcached-php-81}` | -| MongoDB | `${bref-extra:mongodb-php-81}` | -| MsgPack | `${bref-extra:msgpack-php-81}` | -| Newrelic | `${bref-extra:newrelic-php-81}` | -| ODBC Snowflake | `${bref-extra:odbc-snowflake-php-81}` | -| OpenSwoole | `${bref-extra:openswoole-php-81}` | -| Oracle | `${bref-extra:oci8-php-80}` | -| Pcov | `${bref-extra:pcov-php-81}` | -| PostgreSQL | `${bref-extra:pgsql-php-81}` | -| RdKafka | `${bref-extra:rdkafka-php-81}` | -| Redis (phpredis) | `${bref-extra:redis-php-81}` | -| Redis-Igbinary | `${bref-extra:redis-igbinary-php-81}` | -| Relay | `${bref-extra:relay-php-81}` | -| Scout APM | `${bref-extra:scoutapm-php-81}` | -| Scrypt | `${bref-extra:scrypt-php-81}` | -| SPX | `${bref-extra:spx-php-81}` | -| SSH2 | `${bref-extra:ssh2-php-81}` | -| Swoole | `${bref-extra:swoole-php-81}` | -| Symfony Runtime | `${bref-extra:symfony-runtime-php-81}`| -| Microsoft SQLSRV | `${bref-extra:sqlsrv-php-81}` | -| Tideways | `${bref-extra:tideways-php-81}` | -| Tidy | `${bref-extra:tidy-php-81}` | -| UUID | `${bref-extra:uuid-php-81}` | -| Xdebug | `${bref-extra:xdebug-php-81}` | -| Xlswriter | `${bref-extra:xlswriter-php-81}` | -| Yaml | `${bref-extra:yaml-php-81}` | +| Name | Serverless config (php 8.1) | +|:-----------------|:---------------------------------------| +| AMQP | `${bref-extra:amqp-php-81}` | +| Blackfire | `${bref-extra:blackfire-php-81}` | +| Bsdiff | `${bref-extra:bsdiff-php-81}` | +| Calendar | `${bref-extra:calendar-php-81}` | +| Cassandra | `${bref-extra:cassandra-php-81}` | +| Datadog | `${bref-extra:datadog-php-81}` | +| Decimal | `${bref-extra:decimal-php-81}` | +| DS | `${bref-extra:ds-php-81}` | +| Elastic APM | `${bref-extra:elastic-apm-php-81}` | +| GD | `${bref-extra:gd-php-81}` | +| gnupg | `${bref-extra:gnupg-php-81}` | +| GMP | `${bref-extra:gmp-php-81}` | +| gRPC | `${bref-extra:grpc-php-81}` | +| Igbinary | `${bref-extra:igbinary-php-81}` | +| Imagick | `${bref-extra:imagick-php-81}` | +| IMAP | `${bref-extra:imap-php-81}` | +| LDAP | `${bref-extra:ldap-php-81}` | +| Mailparse | `${bref-extra:mailparse-php-81}` | +| MaxMind DB | `${bref-extra:maxminddb-php-81}` | +| Memcache | `${bref-extra:memcache-php-81}` | +| Memcached | `${bref-extra:memcached-php-81}` | +| MongoDB | `${bref-extra:mongodb-php-81}` | +| MsgPack | `${bref-extra:msgpack-php-81}` | +| Newrelic | `${bref-extra:newrelic-php-81}` | +| ODBC Snowflake | `${bref-extra:odbc-snowflake-php-81}` | +| OpenSwoole | `${bref-extra:openswoole-php-81}` | +| Oracle | `${bref-extra:oci8-php-80}` | +| Pcov | `${bref-extra:pcov-php-81}` | +| PostgreSQL | `${bref-extra:pgsql-php-81}` | +| RdKafka | `${bref-extra:rdkafka-php-81}` | +| Redis (phpredis) | `${bref-extra:redis-php-81}` | +| Redis-Igbinary | `${bref-extra:redis-igbinary-php-81}` | +| Relay | `${bref-extra:relay-php-81}` | +| Scout APM | `${bref-extra:scoutapm-php-81}` | +| Scrypt | `${bref-extra:scrypt-php-81}` | +| SPX | `${bref-extra:spx-php-81}` | +| SSH2 | `${bref-extra:ssh2-php-81}` | +| Swoole | `${bref-extra:swoole-php-81}` | +| Symfony Runtime | `${bref-extra:symfony-runtime-php-81}` | +| Microsoft SQLSRV | `${bref-extra:sqlsrv-php-81}` | +| Tideways | `${bref-extra:tideways-php-81}` | +| Tidy | `${bref-extra:tidy-php-81}` | +| UUID | `${bref-extra:uuid-php-81}` | +| Xdebug | `${bref-extra:xdebug-php-81}` | +| Xlswriter | `${bref-extra:xlswriter-php-81}` | +| Yaml | `${bref-extra:yaml-php-81}` | ### Blackfire installation @@ -142,6 +143,10 @@ in your `serverless.yaml` in order to tell unixODBC to load the required ini fil Read [the New Relic tutorial](docs/newrelic.md). +### Datadog + +Read [the Datadog tutorial](docs/datadog.md). + ## Docker images There are Docker images for every layer. They are updated on every push to master diff --git a/docs/datadog.md b/docs/datadog.md new file mode 100644 index 00000000..e961e1d4 --- /dev/null +++ b/docs/datadog.md @@ -0,0 +1,86 @@ +### Datadog installation + +This layer enables the installation of only the Datadog PHP extension. + +To use the extension, you must also install the Datadog agent. +You can achieve this by installing another Datadog Lambda Extension layer. +For more information see https://docs.datadoghq.com/serverless/installation/python/?tab=custom the "Install the Datadog Lambda Extension" section. + +If you are running an x86-based Lambda in AWS commercial regions, use the following ARN: +`arn:aws:lambda::464622532012:layer:Datadog-Extension:` + +If you are running an ARM-based Lambda in AWS commercial regions, use the following ARN: +`arn:aws:lambda::464622532012:layer:Datadog-Extension-ARM:` + +## Configuration + +After installing the layer and the agent, you must configure the Datadog extension by adding the following key/value pair to a Lambda environment variable: + +- `DD_ENV=` +- `DD_SERVICE=` +- `DD_SITE=` (depending on your Datadog account region) +- `DD_API_KEY=` +- `DD_SERVICE=` +- `DD_VERSION=` + +For more details about the configuration, see https://docs.datadoghq.com/tracing/trace_collection/library_config/php/ + +You should also consider adding similar AWS tags to your Lambda function to link APM and Infrastructure data together using the tag/value syntax: + +- `Env=` +- `Service=` +- `Team=` (use `a-z0-9\-` pattern) +- `Tier=` (to indicate how important the service is) + +Find more about infrastructure tagging: + - https://www.datadoghq.com/blog/tagging-best-practices/ + - https://learn.datadoghq.com/courses/tagging-best-practices (online course) + - Enroll in free technical sessions at https://www.datadoghq.com/technical-enablement/sessions/ + +## Custom instrumentation + +DataDog works out of the box with the php-xx-fpm runtime. However, if you are using the php-xx runtime and BREF_LOOP_MAX>1, you must add custom instrumentation. +Otherwise, DataDog will wait until the end of a loop and only send one trace. +To add custom instrumentation, create an `instrumentation.php` file and add the following code: + +```php +service = getenv('DD_SERVICE'); + $span->type = \DDTrace\Type::CLI; + $span->name = 'invoke'; + } +); +``` + +This code will enable you to see all traces. + +*do not forget to add `instrumentation.php` to a `composer.json` file + +For EventBridge Lambdas, add the following code to the function above: + +```php +resource = $args[0]->getDetailType(); + } +``` + +This code will name your traces with the EventBridge event name. + +For more information about custom instrumentation, refer to the following resources: + + - https://github.com/DataDog/dd-trace-php/blob/master/examples/long-running/long-running-script.php + - https://docs.datadoghq.com/tracing/trace_collection/custom_instrumentation/php/?tab=currentspan + - to link traces with a parent one: https://docs.datadoghq.com/tracing/trace_collection/trace_context_propagation/php/ + +## service.datadog.yaml + +Consider also creating a `service.datadog.yaml` file in the root of your project. +It will give you more control over the traces and ability to add links to documentation and contact information. + +To find more: https://www.datadoghq.com/blog/manage-service-catalog-categories-with-service-definition-json-schema/ diff --git a/layers/datadog/Dockerfile b/layers/datadog/Dockerfile new file mode 100644 index 00000000..186f27cd --- /dev/null +++ b/layers/datadog/Dockerfile @@ -0,0 +1,33 @@ +ARG PHP_VERSION +ARG BREF_VERSION +FROM bref/build-php-$PHP_VERSION:$BREF_VERSION AS ext + +ENV DDTRACE_BUILD_DIR=${BUILD_DIR}/ddtrace + +RUN set -xe; \ + mkdir -p ${DDTRACE_BUILD_DIR}; \ + curl -Ls -o ${DDTRACE_BUILD_DIR}/datadog-setup.php \ + https://github.com/DataDog/dd-trace-php/releases/latest/download/datadog-setup.php + +WORKDIR ${DDTRACE_BUILD_DIR} + +RUN php datadog-setup.php --php-bin=all --enable-profiling + +RUN cp "$(php-config --extension-dir)/ddtrace.so" /tmp/ddtrace.so && \ + cp "$(php-config --extension-dir)/datadog-profiling.so" /tmp/datadog-profiling.so && \ + cp "$(php-config --ini-dir)/98-ddtrace.ini" /tmp/ext.ini + +RUN sed -i 's/extension = ddtrace\.so/extension = \/opt\/bref-extra\/ddtrace.so/' /tmp/ext.ini && \ + sed -i 's/extension = datadog-profiling\.so/extension = \/opt\/bref-extra\/datadog-profiling.so/' /tmp/ext.ini && \ + sed -i 's/;datadog\.agent_host.*$/datadog\.agent_host = 127.0.0.1/' /tmp/ext.ini && \ + sed -i 's/^.*datadog\.appsec\.enabled.*$/datadog.appsec.enabled = Off/' /tmp/ext.ini && \ + sed -i 's/datadog\.profiling\.enabled = On/datadog.profiling.enabled = 1/' /tmp/ext.ini + +# Build the final image with just the files we need +FROM scratch + +# Copy things we installed to the final image +COPY --from=ext /tmp/ddtrace.so /opt/bref-extra/ddtrace.so +COPY --from=ext /tmp/datadog-profiling.so /opt/bref-extra/datadog-profiling.so +COPY --from=ext /tmp/ext.ini /opt/bref/etc/php/conf.d/98-ddtrace.ini +COPY --from=ext /opt/datadog/ /opt/datadog diff --git a/layers/datadog/config.json b/layers/datadog/config.json new file mode 100644 index 00000000..a5a35316 --- /dev/null +++ b/layers/datadog/config.json @@ -0,0 +1,7 @@ +{ + "php": [ + "80", + "81", + "82" + ] +} diff --git a/layers/datadog/test.php b/layers/datadog/test.php new file mode 100644 index 00000000..cf685074 --- /dev/null +++ b/layers/datadog/test.php @@ -0,0 +1,8 @@ +