[META 388] Proposal for collecting Azure App Service cloud metadata #365
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -99,6 +99,112 @@ metadata is available. | |
| A sample implementation of this metadata collection is available in | ||
| [the Python agent](https://github.com/elastic/apm-agent-python/blob/master/elasticapm/utils/cloud.py). | ||
|
|
||
| #### AWS metadata | ||
|
|
||
| [Metadata about an EC2 instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html) can be retrieved from the internal metadata endpoint, `http://169.254.169.254`. | ||
|
|
||
| As an example with curl, first, an API token must be created | ||
|
|
||
| ```sh | ||
| TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 300"` | ||
| ``` | ||
|
|
||
| Then, metadata can be retrieved, passing the API token | ||
|
|
||
| ```sh | ||
| curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data | ||
| ``` | ||
|
|
||
| From the returned metadata, the following fields are useful | ||
|
|
||
| | Cloud metadata field | AWS Metadata field | | ||
| | -------------------- | ------------------- | | ||
| | `account.id` | `accountId` | | ||
| | `instance.id` | `instanceId` | | ||
| | `availability_zone` | `availabilityZone` | | ||
| | `machine.type` | `instanceType` | | ||
| | `provider` | aws | | ||
| | `region` | `region` | | ||
|
|
||
| #### GCP metadata | ||
|
|
||
| Metadata about a GCP machine instance can be retrieved from the | ||
| metadata service, `http://metadata.google.internal`. | ||
|
|
||
| An example with curl | ||
|
|
||
| ```sh | ||
| curl -X GET "http://metadata.google.internal/computeMetadata/v1/?recursive=true" -H "Metadata-Flavor: Google" | ||
| ``` | ||
|
|
||
| From the returned metadata, the following fields are useful | ||
|
|
||
| | Cloud metadata field | AWS Metadata field | | ||
| | -------------------- | ------------------- | | ||
| | `instance.id` | `instance.id` | | ||
| | `instance.name` | `instance.name` | | ||
| | `project.id` | `project.numericProjectId` as a string | | ||
| | `project.name` | `project.projectId` | | ||
| | `availability_zone` | last part of `instance.zone`, split by `/` | | ||
| | `machine.type` | last part of `instance.machineType`, split by `/` | | ||
| | `provider` | gcp | | ||
| | `region` | last part of `instance.zone`, split by `-` | | ||
|
|
||
| #### Azure metadata | ||
|
|
||
| ##### Azure VMs | ||
|
|
||
| Metadata about an Azure VM can be retrieved from the internal metadata | ||
| endpoint, `http://169.254.169.254`. | ||
|
|
||
| An example with curl | ||
|
|
||
| ```sh | ||
| curl -X GET "http://169.254.169.254/metadata/instance/compute?api-version=2019-08-15" -H "Metadata: true" | ||
| ``` | ||
|
|
||
| From the returned metadata, the following fields are useful | ||
|
|
||
| | Cloud metadata field | AWS Metadata field | | ||
| | -------------------- | ------------------- | | ||
| | `account.id` | `subscriptionId` | | ||
| | `instance.id` | `vmId` | | ||
| | `instance.name` | `name` | | ||
| | `project.name` | `resourceGroupName` | | ||
| | `availability_zone` | `zone` | | ||
| | `machine.type` | `vmSize` | | ||
| | `provider` | azure | | ||
| | `region` | `location` | | ||
|
|
||
| ##### Azure App Services _(Optional)_ | ||
|
|
||
| Azure App Services are a PaaS offering within Azure which does not | ||
| have access to the internal metadata endpoint. Metadata about | ||
| an App Service can however be retrieved from environment variables | ||
|
|
||
russcam marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| | Cloud metadata field | Environment variable | | ||
| | -------------------- | ------------------- | | ||
| | `account.id` | first part of `WEBSITE_OWNER_NAME`, split by `+` | | ||
| | `instance.id` | `WEBSITE_INSTANCE_ID` | | ||
| | `instance.name` | `WEBSITE_SITE_NAME` | | ||
| | `project.name` | `WEBSITE_RESOURCE_GROUP` | | ||
| | `provider` | azure | | ||
|
There was a problem hiding this comment. Is there value in capturing the cloud product, perhaps There was a problem hiding this comment. ++ I think there could be. cloud fields look to be very much intended for VMs e.g. There was a problem hiding this comment. With elastic/ecs#1204 we will have an ECS field for this as of next release - There was a problem hiding this comment. +1 for somehow capturing the fact that this set of metadata is being captured in an |
||
| | `region` | last part of `WEBSITE_OWNER_NAME`, split by `-`, trim end `"webspace"` and anything following | | ||
|
|
||
|
There was a problem hiding this comment. @russcam datapoint: When I deployed a node application via azure app services my region looked like i.e. the What do you think about spec-ing this as splitting by There was a problem hiding this comment. Thanks for the additional data point. Looks like there may be some cross-language and cross-platform differences in environment variable values. For example, the node app value is The extracted region should be I think what might be good for me to do before updating the PR is to deploy some other language app services to see if there is more variation in values. It might be a simple case of updating the |
||
| The environment variable `WEBSITE_OWNER_NAME` has the form | ||
|
|
||
| ``` | ||
| {subscription id}+{app service plan resource group}-{region}webspace{.*} | ||
| ``` | ||
|
|
||
| an example of which is `f5940f10-2e30-3e4d-a259-63451ba6dae4+elastic-apm-AustraliaEastwebspace` | ||
|
|
||
| Cloud metadata for Azure App Services is optional; it is up | ||
| to each agent to determine whether it is useful to implement | ||
| for their language ecosystem. See [azure_app_service_metadata specs](../../tests/agents/gherkin-specs/azure_app_service_metadata.feature) | ||
| for scenarios and expected outcomes. | ||
|
|
||
| ### Global labels | ||
|
|
||
| Events sent by the agents can have labels associated, which may be useful for custom aggregations, or document-level access control. It is possible to add "global labels" to the metadata, which are labels that will be applied to all events sent by an agent. These are only understood by APM Server 7.2 or greater. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| Feature: Extracting Metadata for Azure App Service | ||
|
|
||
| Background: | ||
| Given an instrumented application is configured to collect cloud provider metadata for azure | ||
|
|
||
| Scenario Outline: Azure App Service with all environment variables present in expected format | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_OWNER_NAME | <WEBSITE_OWNER_NAME> | | ||
| | WEBSITE_RESOURCE_GROUP | resource_group | | ||
| | WEBSITE_SITE_NAME | site_name | | ||
| | WEBSITE_INSTANCE_ID | instance_id | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is not null | ||
| And cloud metadata 'account.id' is 'f5940f10-2e30-3e4d-a259-63451ba6dae4' | ||
| And cloud metadata 'provider' is 'azure' | ||
| And cloud metadata 'instance.id' is 'instance_id' | ||
| And cloud metadata 'instance.name' is 'site_name' | ||
| And cloud metadata 'project.name' is 'resource_group' | ||
| And cloud metadata 'region' is 'AustraliaEast' | ||
| Examples: | ||
| | WEBSITE_OWNER_NAME | | ||
| | f5940f10-2e30-3e4d-a259-63451ba6dae4+elastic-apm-AustraliaEastwebspace | | ||
| | f5940f10-2e30-3e4d-a259-63451ba6dae4+appsvc_linux_australiaeast-AustraliaEastwebspace-Linux | | ||
|
|
||
| # WEBSITE_OWNER_NAME is expected to include a + character | ||
| Scenario: WEBSITE_OWNER_NAME environment variable not expected format | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_OWNER_NAME | f5940f10-2e30-3e4d-a259-63451ba6dae4-elastic-apm-AustraliaEastwebspace | | ||
| | WEBSITE_RESOURCE_GROUP | resource_group | | ||
| | WEBSITE_SITE_NAME | site_name | | ||
| | WEBSITE_INSTANCE_ID | instance_id | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is null | ||
|
|
||
| Scenario: Missing WEBSITE_OWNER_NAME environment variable | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_RESOURCE_GROUP | resource_group | | ||
| | WEBSITE_SITE_NAME | site_name | | ||
| | WEBSITE_INSTANCE_ID | instance_id | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is null | ||
|
|
||
| Scenario: Missing WEBSITE_RESOURCE_GROUP environment variable | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_OWNER_NAME | f5940f10-2e30-3e4d-a259-63451ba6dae4+elastic-apm-AustraliaEastwebspace | | ||
| | WEBSITE_SITE_NAME | site_name | | ||
| | WEBSITE_INSTANCE_ID | instance_id | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is null | ||
|
|
||
| Scenario: Missing WEBSITE_SITE_NAME environment variable | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_OWNER_NAME | f5940f10-2e30-3e4d-a259-63451ba6dae4+elastic-apm-AustraliaEastwebspace | | ||
| | WEBSITE_RESOURCE_GROUP | resource_group | | ||
| | WEBSITE_INSTANCE_ID | instance_id | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is null | ||
|
|
||
| Scenario: Missing WEBSITE_INSTANCE_ID environment variable | ||
| Given the following environment variables are present | ||
| | name | value | | ||
| | WEBSITE_OWNER_NAME | f5940f10-2e30-3e4d-a259-63451ba6dae4+elastic-apm-AustraliaEastwebspace | | ||
| | WEBSITE_RESOURCE_GROUP | resource_group | | ||
| | WEBSITE_SITE_NAME | site_name | | ||
| When cloud metadata is collected | ||
| Then cloud metadata is null |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What @axw said in an earlier comment:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The presence of
WEBSITE_*environment variables and the format ofWEBSITE_OWNER_NAMEshould be sufficient.