OpenTelemetry Resource Detector for AWS

[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]

component owners: @jj22ee

Resource detector for Amazon Web Services.

Status

| Maturity | Component Owner | Compatibility |
|----------------------------------------|-------------------------------------------------------|-----------------------|
| Stable | @jj22ee | API 1.0+
SDK 1.0+ |

Installation

``bash
npm install --save @opentelemetry/resource-detector-aws
`

Usage

`typescript
import { detectResources } from '@opentelemetry/resources';
import { awsEc2Detector } from '@opentelemetry/resource-detector-aws'
const resource = await detectResources({
detectors: [awsEc2Detector],
})

const tracerProvider = new NodeTracerProvider({ resource });
`

Available detectors

This package uses @opentelemetry/semantic-conventions version 1.22+, which implements Semantic Convention Version 1.7.0

$3

Populates service for processes running on AWS Elastic Beanstalk

| Resource Attribute | Description |
|---------------------|--------------------------------------------------------------------------|
| cloud.platform | The cloud platform. In this context, it's always "aws_elastic_beanstalk" |
| cloud.provider | The cloud provider. In this context, it's always "aws" |
| service.instance.id | Value of deployment_id from config file environment.conf |
| service.name | The service name. In this context, it's always "aws_elastic_beanstalk" |
| service.namespace | Value of environment_name from config file environment.conf |
| service.version | Value of version_label from config file environment.conf |

$3

Populates cloud and host for processes running on Amazon EC2, including abstractions such as ECS on EC2. Notably, it does not populate anything on AWS Fargate.

| Resource Attribute | Description |
|-------------------------|---------------------------------------------------------------------------------------|
| cloud.account.id | Value of accountId from /latest/dynamic/instance-identity/document request |
| cloud.availability_zone | Value of availabilityZone from /latest/dynamic/instance-identity/document request |
| cloud.platform | The cloud platform. In this context, it's always "aws_ec2" |
| cloud.provider | The cloud provider. In this context, it's always "aws" |
| cloud.region | Value of region from /latest/dynamic/instance-identity/document request |
| host.id | Value of instanceId from /latest/dynamic/instance-identity/document request |
| host.name | Value of hostname from /latest/dynamic/instance-identity/document request |
| host.type | Value of instanceType from /latest/dynamic/instance-identity/document request |

$3

Populates container for containers running on Amazon ECS.

| Resource Attribute | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| aws.ecs.container.arn | Value of ContainerARN from the request to the metadata Uri. The Metadata Uri is stored on the Environment Variable ECS_CONTAINER_METADATA_URI_V4 |
| aws.ecs.cluster.arn | Value in the format ${baseArn}:cluster/${cluster}, with baseArn and cluster from a ECS_CONTAINER_METADATA_URI_V4/task request, with values from TaskARN and Cluster respectively |
| aws.ecs.launchtype | Value of LaunchType from ECS_CONTAINER_METADATA_URI_V4/task request |
| aws.ecs.task.arn | Value of TaskARN from ECS_CONTAINER_METADATA_URI_V4/task request |
| aws.ecs.task.family | Value of Family from ECS_CONTAINER_METADATA_URI_V4/task request |
| aws.ecs.task.revision | Value of Revision from ECS_CONTAINER_METADATA_URI_V4/task request |
| aws.log.group.arns | Value on format arn:aws:logs:${logsRegion}:${awsAccount}:log-group:${logsGroupName}, with logsRegions and logsGroupName from logs metadata, values of awslogs-region and awslogs-group respectively, and awsAccount parsed value from the TaskARN. Logs metadata values come from LogOptions on ECS_CONTAINER_METADATA_URI_V4 request |
| aws.log.group.names | Value of awslogs-group from logs metadata. Logs metadata values come from LogOptions on ECS_CONTAINER_METADATA_URI_V4 request |
| aws.log.stream.arns | Value on format arn:aws:logs:${logsRegion}:${awsAccount}:log-group:${logsGroupName}:log-stream:${logsStreamName}, with logsRegions, logsGroupName and logsStreamName from logs metadata, values of awslogs-region, awslogs-group and awslogs-stream respectively, and awsAccount parsed value from the TaskARN |
| aws.log.stream.names | Value of awslogs-stream from logs metadata |
| cloud.account.id | Parsed value from the TaskARN |
| cloud.availability_zone | Value of AvailabilityZone from ECS_CONTAINER_METADATA_URI_V4/task request. This value is not available in all Fargate runtimes |
| cloud.platform | The cloud platform. In this context, it's always "aws_ecs" |
| cloud.provider | The cloud provider. In this context, it's always "aws" |
| cloud.region | Parsed value from the TaskARN |
| cloud.resource_id | Value of ContainerARN from ECS_CONTAINER_METADATA_URI_V4/task request |
| container.id | Value from file /proc/self/cgroup |
| container.name | The hostname of the operating system |

$3

Populates container and k8s.cluster_name for containers running on Amazon EKS.
k8s.cluster_name is not always available depending on the configuration of CloudWatch monitoring for the EKS cluster.

| Resource Attribute | Description |
|--------------------|-----------------------------------------------------------------------------------------------------|
| cloud.platform | The cloud platform. In this context, it's always "aws_eks" |
| cloud.provider | The cloud provider. In this context, it's always "aws" |
| container.id | Value from config file /proc/self/cgroup |
| k8s.cluster.name | Value of cluster.name from /api/v1/namespaces/amazon-cloudwatch/configmaps/cluster-info request |

$3

Populates faas and cloud for functions running on AWS Lambda.
faas.id is currently not populated as it is not provided by the runtime at startup.

| Resource Attribute | Description |
|--------------------|---------------------------------------------------------------------|
| cloud.platform | The cloud platform. In this context, it's always "aws_lambda" |
| cloud.provider | The cloud provider. In this context, it's always "aws" |
| cloud.region | Value of Process Environment Variable AWS_REGION |
| faas.name | Value of Process Environment Variable AWS_LAMBDA_FUNCTION_NAME |
| faas.version | Value of Process Environment Variable AWS_LAMBDA_FUNCTION_VERSION` |

Useful links

- For more information on OpenTelemetry, visit:
- For more about OpenTelemetry JavaScript:
- For help or feedback on this project, join us in [GitHub Discussions][discussions-url]

License

Apache 2.0 - See [LICENSE][license-url] for more information.

[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/resource-detector-aws
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fresource-detector-aws.svg