From 5b9fd1e1f79a0f4da4899048bc1ad6bd969fd12a Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Mon, 27 Sep 2021 13:36:50 +0200 Subject: [PATCH 1/5] add user-agent spec + gherkin spec --- specs/agents/transport.md | 13 +++++++++++++ tests/agents/gherkin-specs/user_agent.feature | 19 +++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 tests/agents/gherkin-specs/user_agent.feature diff --git a/specs/agents/transport.md b/specs/agents/transport.md index 95126b4b..7a8e22de 100644 --- a/specs/agents/transport.md +++ b/specs/agents/transport.md @@ -2,6 +2,19 @@ Agents send data to the APM Server as JSON (application/json) or ND-JSON (application/x-ndjson) over HTTP. We describe here various details to guide transport implementation. +### User-Agent + +In order to help debugging and gathering usage statistics, agents should use one following values for the `User-Agent` HTTP header: + +- Header value should start with `elasticapm-${language}/${agent.version}`. +- If both `service.name` and `service.version` are set, append ` ${service.name}/${service.version}` +- If only `service.name` is set, append `${service.name}` + +Examples: +- `elasticapm-java/v1.25.0` +- `elasticapm-ruby/4.4.0 myservice` +- `elasticapm-python/6.4.0 myservice/v42.7` + ### Background sending In order to avoid impacting application performance and behaviour, agents should (where possible) send data in a non-blocking manner, e.g. via a background thread/goroutine/process/what-have-you, or using asynchronous I/O. diff --git a/tests/agents/gherkin-specs/user_agent.feature b/tests/agents/gherkin-specs/user_agent.feature new file mode 100644 index 00000000..18f4690e --- /dev/null +++ b/tests/agents/gherkin-specs/user_agent.feature @@ -0,0 +1,19 @@ +Feature: Agent Transport User agent Header + + Scenario: Default user-agent + Given an agent + When service name is not set + When service version is not set + Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]*' + + Scenario: User-agent with service name only + Given an agent + When service name is set to 'myService' + When service version is not set + Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]* myService' + + Scenario: User-agent with service name and service version + Given an agent + When service name is set to 'myService' + When service version is set to 'v42' + Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]* myService/v42' From 65a08b671e3ea865d21595c47e4b3e1ca3801e31 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Mon, 27 Sep 2021 14:30:02 +0200 Subject: [PATCH 2/5] update regex --- tests/agents/gherkin-specs/user_agent.feature | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/agents/gherkin-specs/user_agent.feature b/tests/agents/gherkin-specs/user_agent.feature index 18f4690e..67969524 100644 --- a/tests/agents/gherkin-specs/user_agent.feature +++ b/tests/agents/gherkin-specs/user_agent.feature @@ -4,16 +4,16 @@ Feature: Agent Transport User agent Header Given an agent When service name is not set When service version is not set - Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]*' + Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]*' Scenario: User-agent with service name only Given an agent When service name is set to 'myService' When service version is not set - Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]* myService' + Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]* myService' Scenario: User-agent with service name and service version Given an agent When service name is set to 'myService' When service version is set to 'v42' - Then the User-Agent header matches regex 'elasticapm-(java|ruby|python|dotnet|nodejs|go|php)/[^ ]* myService/v42' + Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]* myService/v42' From 870dfbeba523c72cf2ac0c027d73670589580af2 Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Tue, 28 Sep 2021 10:55:01 +0200 Subject: [PATCH 3/5] make regex a bit more strict --- tests/agents/gherkin-specs/user_agent.feature | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/agents/gherkin-specs/user_agent.feature b/tests/agents/gherkin-specs/user_agent.feature index 67969524..c90a72b7 100644 --- a/tests/agents/gherkin-specs/user_agent.feature +++ b/tests/agents/gherkin-specs/user_agent.feature @@ -4,16 +4,16 @@ Feature: Agent Transport User agent Header Given an agent When service name is not set When service version is not set - Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]*' + Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]*' Scenario: User-agent with service name only Given an agent When service name is set to 'myService' When service version is not set - Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]* myService' + Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]* myService' Scenario: User-agent with service name and service version Given an agent When service name is set to 'myService' When service version is set to 'v42' - Then the User-Agent header matches regex 'elasticapm-[a-z]+/[^ ]* myService/v42' + Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]* myService/v42' From ab86083ce610a9657706417039f958eddc48e782 Mon Sep 17 00:00:00 2001 From: SylvainJuge Date: Wed, 29 Sep 2021 09:42:51 +0200 Subject: [PATCH 4/5] wording fix specs/agents/transport.md Co-authored-by: Trent Mick --- specs/agents/transport.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/agents/transport.md b/specs/agents/transport.md index 7a8e22de..02ffb838 100644 --- a/specs/agents/transport.md +++ b/specs/agents/transport.md @@ -4,7 +4,7 @@ Agents send data to the APM Server as JSON (application/json) or ND-JSON (applic ### User-Agent -In order to help debugging and gathering usage statistics, agents should use one following values for the `User-Agent` HTTP header: +In order to help debugging and gathering usage statistics, agents should use one of the following values for the `User-Agent` HTTP header: - Header value should start with `elasticapm-${language}/${agent.version}`. - If both `service.name` and `service.version` are set, append ` ${service.name}/${service.version}` From 0e2bc444cc9453a66456cc64ce4a85bcbf80b29d Mon Sep 17 00:00:00 2001 From: Sylvain Juge Date: Mon, 11 Oct 2021 16:54:39 +0200 Subject: [PATCH 5/5] align spec to es-client user-agent header --- specs/agents/transport.md | 14 ++++++++------ tests/agents/gherkin-specs/user_agent.feature | 6 +++--- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/specs/agents/transport.md b/specs/agents/transport.md index 02ffb838..5ad80ba7 100644 --- a/specs/agents/transport.md +++ b/specs/agents/transport.md @@ -6,14 +6,16 @@ Agents send data to the APM Server as JSON (application/json) or ND-JSON (applic In order to help debugging and gathering usage statistics, agents should use one of the following values for the `User-Agent` HTTP header: -- Header value should start with `elasticapm-${language}/${agent.version}`. -- If both `service.name` and `service.version` are set, append ` ${service.name}/${service.version}` -- If only `service.name` is set, append `${service.name}` +- Header value should start with agent github repository as prefix and version `apm-agent-${language}/${agent.version}`. +- If both `service.name` and `service.version` are set, append ` (${service.name} ${service.version})` +- If only `service.name` is set, append `(${service.name})` + +An executable gherkin specification is also provided in [user_agent.feature](../../tests/agents/gherkin-specs/user_agent.feature). Examples: -- `elasticapm-java/v1.25.0` -- `elasticapm-ruby/4.4.0 myservice` -- `elasticapm-python/6.4.0 myservice/v42.7` +- `apm-agent-java/v1.25.0` +- `apm-agent-ruby/4.4.0 (myservice)` +- `apm-agent-python/6.4.0 (myservice v42.7)` ### Background sending diff --git a/tests/agents/gherkin-specs/user_agent.feature b/tests/agents/gherkin-specs/user_agent.feature index c90a72b7..411909c0 100644 --- a/tests/agents/gherkin-specs/user_agent.feature +++ b/tests/agents/gherkin-specs/user_agent.feature @@ -4,16 +4,16 @@ Feature: Agent Transport User agent Header Given an agent When service name is not set When service version is not set - Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]*' + Then the User-Agent header matches regex '^apm-agent-[a-z]+/[^ ]*' Scenario: User-agent with service name only Given an agent When service name is set to 'myService' When service version is not set - Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]* myService' + Then the User-Agent header matches regex '^apm-agent-[a-z]+/[^ ]* \(myService\)' Scenario: User-agent with service name and service version Given an agent When service name is set to 'myService' When service version is set to 'v42' - Then the User-Agent header matches regex '^elasticapm-[a-z]+/[^ ]* myService/v42' + Then the User-Agent header matches regex '^apm-agent-[a-z]+/[^ ]* \(myService v42\)'