docs: Add PHP agent information to shared docs #4740

bmorelli25 · 2021-02-16T19:31:52Z

Summary

This PR adds PHP agent information to the following documentation pages:

Observability Guide

Instrument apps

APM Overview

Components
Quick start
Dropped spans
Transaction sample rate config
SetLabel/SetContext/SetUser These API methods don't exist yet. Marked as coming soon.
Distributed tracing: I'll need your help with an example on this one. We need an example for adding traceparent to outgoing requests, and one to receive the incoming context.
Agent/Server compatibility
What is the minimum supported APM Server version for 1.0?
Troubleshooting
~~- [ ] Metrics~~ No metrics documentation yet. Skipping for now.
~~- [ ] OpenTracing Bridge~~ No OpenTracing bridge. Unplanned. Skipping for now.

APM Server Reference

Related issues

For elastic/observability-docs#383.

~~Blocked by elastic/apm-agent-php#352. Docs ci will not pass until 352 is merged.~~

bmorelli25 · 2021-02-16T19:32:26Z

@SergeyKleyman, please see the questions in the description above.

apmmachine · 2021-02-16T20:21:00Z

💚 Build Succeeded

the below badges are clickable and redirect to their specific view in the CI or DOCS

Expand to view the summary

Build stats

Build Cause: Pull request #4740 updated
Start Time: 2021-02-19T17:44:20.789+0000
Duration: 46 min 27 sec
Commit: d538023

Test stats 🧪

Test	Results
Failed	0
Passed	4751
Skipped	124
Total	4875

Trends 🧪

Steps errors

Expand to view the steps failures

`Run Window tests`

Took 10 min 0 sec . View more details on here

`Test Sync`

Took 3 min 28 sec . View more details on here
Description: ./.ci/scripts/sync.sh

SergeyKleyman · 2021-02-17T18:24:36Z

No OpenTracing bridge. Will there ever be one?

OpenTracing bridge is definitely not planned for PHP Agent 1.0 and I'm not sure if it will ever be added especially considering that OpenTracing is superseded by OpenTelemetry. If we get requests from users we will reconsider it.

What is the minimum supported APM Server version for 1.0?

For PHP Agent 1.0 minimum supported APM Server version is 7.0.

bmorelli25 · 2021-02-18T18:39:38Z

@elasticmachine, run elasticsearch-ci/docs

codecov-io · 2021-02-18T18:58:32Z

Codecov Report

Merging #4740 (d538023) into master (ce812f6) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #4740   +/-   ##
=======================================
  Coverage   76.81%   76.81%           
=======================================
  Files         166      166           
  Lines       10244    10244           
=======================================
  Hits         7869     7869           
  Misses       2375     2375

Impacted Files	Coverage Δ
...ack/apm-server/aggregation/txmetrics/aggregator.go	`93.36% <0.00%> (ø)`

SergeyKleyman · 2021-02-18T18:39:43Z

docs/guide/apm-data-model.asciidoc

@@ -53,6 +53,7 @@ To configure the number of spans recorded per transaction, see the relevant Agen
 * Java: {apm-java-ref-v}/config-core.html#config-transaction-max-spans[`transaction_max_spans`]
 * .NET: {apm-dotnet-ref-v}/config-core.html#config-transaction-max-spans[`TransactionMaxSpans`]
 * Node.js: {apm-node-ref-v}/configuration.html#transaction-max-spans[`transactionMaxSpans`]
+* PHP: {apm-php-ref}/configuration-reference.html#config-transaction-max-spans[`transaction_max_spans`]


What is the difference between apm-<language>-ref and apm-<language>-ref-v?

Great catch! You're right, I should be using the -v attribute, which stands for version. The apm-<language>-ref resolves from here. It permanently links to current.

The apm-<language>-ref-v resolves from here, using the additional attributes described here. It points to the current version of the documentation as well, but allows us to pin agent versions to stack versions. This makes updating links as documentation evolves much easier.

Fixed in bc51362.

docs/guide/apm-data-model.asciidoc

docs/tab-widgets/distributed-trace-receive.asciidoc

Co-authored-by: Sergey Kleyman <[email protected]>

…lli25/apm-server into add-php-agent-instructions

docs/version.asciidoc

bmorelli25 · 2021-02-19T00:30:41Z

Thank you @SergeyKleyman! I'll wait for one of the @elastic/obs-docs writers to give final approval before merging this PR.

SergeyKleyman · 2021-02-19T12:26:37Z

docs/tab-widgets/distributed-trace-receive.asciidoc

+
+2. Begin a new transaction using the agent's public API. For example, use {apm-php-ref-v}/public-api.html#api-elasticapm-class-begin-current-transaction[`ElasticApm::beginCurrentTransaction`]
+and pass the new `DistributedTracingData` object as a parameter.
+This will create a new transaction or span as a child of the incoming trace context.


It's not entirely correct - as name implies beginCurrentTransaction is used to create a new transaction and not a span. I saw some other agents say something similar in this document (i.e., that distributed tracing context on the receiving side can be used to create a new span and not only a new transaction). I am not sure if it's correct for those agents or not - it might be worth making sure with the relevant teams. But for PHP agent distributed tracing context on the receiving side can be passed to create a new transaction but not a new span. A new spans can then be created as children of the new transaction (and the distributed tracing context will passed to them automatically by the new transaction). The confusion might be stemming from the fact that on the sending side the source of the distributed tracing context (that then is passed to the receiving side) can be either transaction or span whatever is the current entity at the point getDistributedTracingData is invoked. That source of the distributed tracing context will then be considered to be the parent of the new transaction on the receiving side.

I am not sure if it's correct for those agents or not - it might be worth making sure with the relevant teams.

Thanks. The agent devs created that content for the most part, but I'll double-check just to be safe. I presume you may be correct and that we can do better with the wording here. I'll save that for a follow-up PR.

The confusion might be stemming from the fact that on the sending side the source of the distributed tracing context (that then is passed to the receiving side) can be either transaction or span whatever is the current entity at the point getDistributedTracingData is invoked.

Yes, that's very helpful. I'll fix.

Addressed in c9b17b5. Will follow up with the other agents in a separate PR.

Co-authored-by: Sergey Kleyman <[email protected]>

Co-authored-by: Sergey Kleyman <[email protected]> Co-authored-by: Sergey Kleyman <[email protected]>

…chemas-to-agents * upstream/master: (111 commits) Introduce metricset.name (elastic#4857) processor/otel: test service.version handling (elastic#4853) docs: Add PHP agent information to shared docs (elastic#4740) Script for faster development workflow (elastic#4731) Update to elastic/beats@1b31c26 (elastic#4763) backport: add 7.12 to .backportrc.json (elastic#4807) backport: enable auto-merge on backport PRs (elastic#4777) Support for Node.js profiles (elastic#4728) docs: readds .NET link (elastic#4764) [DOCS] Fixes URLs on Secure communication with APM Agents page (elastic#4746) ci: set proper parameters for the tar step (elastic#4696) docs: add 7.11.1 release notes (elastic#4727) Disable sourcemap upload endpoint when data streams enabled (elastic#4735) Add service name to dataset field (elastic#4674) Update to elastic/beats@ba423212a660 (elastic#4733) sampling: require a default policy (elastic#4729) processor/otel: add unit test for span status (elastic#4734) Add support for consuming OTLP/gRPC metrics (elastic#4722) [apmpackage] Add config options supported in ESS (elastic#4690) Use the apm-server version everywhere* (elastic#4725) ...

…te-schema-json-1 * upstream/master: (111 commits) Introduce metricset.name (elastic#4857) processor/otel: test service.version handling (elastic#4853) docs: Add PHP agent information to shared docs (elastic#4740) Script for faster development workflow (elastic#4731) Update to elastic/beats@1b31c26 (elastic#4763) backport: add 7.12 to .backportrc.json (elastic#4807) backport: enable auto-merge on backport PRs (elastic#4777) Support for Node.js profiles (elastic#4728) docs: readds .NET link (elastic#4764) [DOCS] Fixes URLs on Secure communication with APM Agents page (elastic#4746) ci: set proper parameters for the tar step (elastic#4696) docs: add 7.11.1 release notes (elastic#4727) Disable sourcemap upload endpoint when data streams enabled (elastic#4735) Add service name to dataset field (elastic#4674) Update to elastic/beats@ba423212a660 (elastic#4733) sampling: require a default policy (elastic#4729) processor/otel: add unit test for span status (elastic#4734) Add support for consuming OTLP/gRPC metrics (elastic#4722) [apmpackage] Add config options supported in ESS (elastic#4690) Use the apm-server version everywhere* (elastic#4725) ...

docs: link to existing PHP content

20d164f

bmorelli25 added docs v7.12.0 labels Feb 16, 2021

bmorelli25 requested a review from SergeyKleyman February 16, 2021 19:31

bmorelli25 self-assigned this Feb 16, 2021

bmorelli25 mentioned this pull request Feb 16, 2021

docs: add boilerplate troubleshooting topic elastic/apm-agent-php#352

Merged

bmorelli25 added 3 commits February 17, 2021 10:17

docs: add more PHP content

0253e04

Merge branch 'master' into add-php-agent-instructions

78fe467

docs: fix accidental overwrite

21a8638

bmorelli25 mentioned this pull request Feb 17, 2021

PHP agent documentation updates elastic/observability-docs#383

Closed

24 tasks

bmorelli25 marked this pull request as ready for review February 18, 2021 18:39

Merge branch 'master' into add-php-agent-instructions

00401a9

SergeyKleyman approved these changes Feb 18, 2021

View reviewed changes

bmorelli25 and others added 4 commits February 18, 2021 15:42

Apply suggestions from code review

81aa27c

Co-authored-by: Sergey Kleyman <[email protected]>

docs: use correct php ref attribute

bc51362

Merge branch 'add-php-agent-instructions' of https://github.com/bmore…

ecc04df

…lli25/apm-server into add-php-agent-instructions

docs: cleanup

47876d1

bmorelli25 requested a review from a team February 18, 2021 23:59

bmorelli25 commented Feb 19, 2021

View reviewed changes

docs/version.asciidoc Outdated Show resolved Hide resolved

Fix doc build errors

d917d24

SergeyKleyman reviewed Feb 19, 2021

View reviewed changes

bmorelli25 added 2 commits February 19, 2021 09:42

docs: fix up receiving context

c9b17b5

Merge branch 'master' into add-php-agent-instructions

d538023

bmorelli25 merged commit 2ce65df into elastic:master Feb 19, 2021

bmorelli25 deleted the add-php-agent-instructions branch February 19, 2021 18:53

bmorelli25 mentioned this pull request Feb 19, 2021

[7.x] docs: Add PHP agent information to shared docs (#4740) #4844

Merged

bmorelli25 added a commit to bmorelli25/apm-server that referenced this pull request Feb 19, 2021

docs: Add PHP agent information to shared docs (elastic#4740)

c97ad22

Co-authored-by: Sergey Kleyman <[email protected]>

bmorelli25 mentioned this pull request Feb 19, 2021

[7.12] docs: Add PHP agent information to shared docs (#4740) #4845

Merged

bmorelli25 added a commit to bmorelli25/apm-server that referenced this pull request Feb 19, 2021

docs: Add PHP agent information to shared docs (elastic#4740)

618e012

Co-authored-by: Sergey Kleyman <[email protected]>

bmorelli25 added a commit that referenced this pull request Feb 19, 2021

docs: Add PHP agent information to shared docs (#4740) (#4844)

49449e6

Co-authored-by: Sergey Kleyman <[email protected]> Co-authored-by: Sergey Kleyman <[email protected]>

bmorelli25 added a commit that referenced this pull request Feb 19, 2021

docs: Add PHP agent information to shared docs (#4740) (#4845)

20a52ec

Co-authored-by: Sergey Kleyman <[email protected]> Co-authored-by: Sergey Kleyman <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add PHP agent information to shared docs #4740

docs: Add PHP agent information to shared docs #4740

bmorelli25 commented Feb 16, 2021 •

edited

Loading

bmorelli25 commented Feb 16, 2021

apmmachine commented Feb 16, 2021 •

edited

Loading

Build stats

Test stats 🧪

Trends 🧪

`Run Window tests`

`Test Sync`

SergeyKleyman commented Feb 17, 2021

bmorelli25 commented Feb 18, 2021

codecov-io commented Feb 18, 2021 •

edited

Loading

SergeyKleyman Feb 18, 2021

bmorelli25 Feb 18, 2021 •

edited

Loading

bmorelli25 Feb 18, 2021

bmorelli25 commented Feb 19, 2021

SergeyKleyman Feb 19, 2021 •

edited

Loading

bmorelli25 Feb 19, 2021 •

edited

Loading

bmorelli25 Feb 19, 2021

docs: Add PHP agent information to shared docs #4740

docs: Add PHP agent information to shared docs #4740

Conversation

bmorelli25 commented Feb 16, 2021 • edited Loading

Summary

Observability Guide

APM Overview

APM Server Reference

Related issues

bmorelli25 commented Feb 16, 2021

apmmachine commented Feb 16, 2021 • edited Loading

💚 Build Succeeded

Build stats

Test stats 🧪

Trends 🧪

Steps errors

Run Window tests

Test Sync

SergeyKleyman commented Feb 17, 2021

bmorelli25 commented Feb 18, 2021

codecov-io commented Feb 18, 2021 • edited Loading

Codecov Report

SergeyKleyman Feb 18, 2021

Choose a reason for hiding this comment

bmorelli25 Feb 18, 2021 • edited Loading

Choose a reason for hiding this comment

bmorelli25 Feb 18, 2021

Choose a reason for hiding this comment

bmorelli25 commented Feb 19, 2021

SergeyKleyman Feb 19, 2021 • edited Loading

Choose a reason for hiding this comment

bmorelli25 Feb 19, 2021 • edited Loading

Choose a reason for hiding this comment

bmorelli25 Feb 19, 2021

Choose a reason for hiding this comment

bmorelli25 commented Feb 16, 2021 •

edited

Loading

apmmachine commented Feb 16, 2021 •

edited

Loading

`Run Window tests`

`Test Sync`

codecov-io commented Feb 18, 2021 •

edited

Loading

bmorelli25 Feb 18, 2021 •

edited

Loading

SergeyKleyman Feb 19, 2021 •

edited

Loading

bmorelli25 Feb 19, 2021 •

edited

Loading