@aws/aws-distro-opentelemetry-node-autoinstrumentation
Version:
This package provides Amazon Web Services distribution of the OpenTelemetry Node Instrumentation, which allows for auto-instrumentation of NodeJS applications.
154 lines • 7.81 kB
TypeScript
import { Resource } from '@opentelemetry/resources';
import { ReadableSpan } from '@opentelemetry/sdk-trace-base';
import { AttributeMap, MetricAttributeGenerator } from './metric-attribute-generator';
/**
* AwsMetricAttributeGenerator generates very specific metric attributes based on low-cardinality
* span and resource attributes. If such attributes are not present, we fallback to default values.
*
* <p>The goal of these particular metric attributes is to get metrics for incoming and outgoing
* traffic for a service. Namely, {@link SpanKind.SERVER} and {@link SpanKind.CONSUMER} spans
* represent "incoming" traffic, {@link SpanKind.CLIENT} and {@link SpanKind.PRODUCER} spans
* represent "outgoing" traffic, and {@link SpanKind.INTERNAL} spans are ignored.
*/
export declare class AwsMetricAttributeGenerator implements MetricAttributeGenerator {
generateMetricAttributeMapFromSpan(span: ReadableSpan, resource: Resource): AttributeMap;
private generateServiceMetricAttributes;
private generateDependencyMetricAttributes;
/** Service is always derived from {@link SEMRESATTRS_SERVICE_NAME} */
private static setService;
/**
* Ingress operation (i.e. operation for Server and Consumer spans) will be generated from
* "http.method + http.target/with the first API path parameter" if the default span name equals
* null, UnknownOperation or http.method value.
*/
private static setIngressOperation;
/**
* Egress operation (i.e. operation for Client and Producer spans) is always derived from a
* special span attribute, {@link AWS_ATTRIBUTE_KEYS.AWS_LOCAL_OPERATION}. This attribute is
* generated with a separate SpanProcessor, {@link AttributePropagatingSpanProcessor}
*/
private static setEgressOperation;
/**
* Remote attributes (only for Client and Producer spans) are generated based on low-cardinality
* span attributes, in priority order.
*
* <p>The first priority is the AWS Remote attributes, which are generated from manually
* instrumented span attributes, and are clear indications of customer intent. If AWS Remote
* attributes are not present, the next highest priority span attribute is Peer Service, which is
* also a reliable indicator of customer intent. If this is set, it will override
* AWS_REMOTE_SERVICE identified from any other span attribute, other than AWS Remote attributes.
*
* <p>After this, we look for the following low-cardinality span attributes that can be used to
* determine the remote metric attributes:
*
* <ul>
* <li>RPC
* <li>DB
* <li>FAAS
* <li>Messaging
* <li>GraphQL - Special case, if {@link _GRAPHQL_OPERATION_TYPE} is present,
* we use it for RemoteOperation and set RemoteService to {@link GRAPHQL}.
* </ul>
*
* <p>In each case, these span attributes were selected from the OpenTelemetry trace semantic
* convention specifications as they adhere to the three following criteria:
*
* <ul>
* <li>Attributes are meaningfully indicative of remote service/operation names.
* <li>Attributes are defined in the specification to be low cardinality, usually with a low-
* cardinality list of values.
* <li>Attributes are confirmed to have low-cardinality values, based on code analysis.
* </ul>
*
* if the selected attributes are still producing the UnknownRemoteService or
* UnknownRemoteOperation, `net.peer.name`, `net.peer.port`, `server.address`, `server.port`,
* `net.peer.sock.addr`, `net.peer.sock.port`, `http.url` and `url.full` will be used to derive
* the RemoteService. And `http.method`, `http.request.method`, `http.url` and `url.full` will be
* used to derive the RemoteOperation.
*/
private static setRemoteServiceAndOperation;
/**
* When the remote call operation is undetermined for http use cases, will try to extract the
* remote operation name from http url string
*/
private static generateRemoteOperation;
private static generateRemoteService;
/**
* If the span is an AWS SDK span, normalize the name to align with <a
* href="https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html">AWS
* Cloud Control resource format</a> as much as possible, with special attention to services we
* can detect remote resource information for. Long term, we would like to normalize service name
* in the upstream.
*
* For Bedrock, Bedrock Agent, and Bedrock Agent Runtime, we can align with AWS Cloud Control and use
* AWS::Bedrock for RemoteService. For BedrockRuntime, we are using AWS::BedrockRuntime
* as the associated remote resource (Model) is not listed in Cloud Control.
*/
private static normalizeRemoteServiceName;
/**
* Remote resource attributes {@link AWS_ATTRIBUTE_KEYS.AWS_REMOTE_RESOURCE_TYPE} and
* {@link AWS_ATTRIBUTE_KEYS.AWS_REMOTE_RESOURCE_IDENTIFIER} are used to store information about the
* resource associated with the remote invocation, such as S3 bucket name, etc. We should only
* ever set both type and identifier or neither. If any identifier value contains | or ^ , they
* will be replaced with ^| or ^^.
*
* <p>AWS resources type and identifier adhere to <a
* href="https://docs.aws.amazon.com/cloudcontrolapi/latest/userguide/supported-resources.html">AWS
* Cloud Control resource format</a>.
*/
private static setRemoteResourceTypeAndIdentifier;
/**
* Remote environment is used to identify the environment of downstream services. Currently only
* set to "lambda:default" for Lambda Invoke operations when aws-api system is detected.
*/
private static setRemoteEnvironment;
private static setRemoteResourceAccountIdAndRegion;
private static setRemoteResourceAccessKeyAndRegion;
/**
* RemoteResourceIdentifier is populated with rule <code>
* ^[{db.name}|]?{address}[|{port}]?
* </code>
*
* <pre>
* {address} attribute is retrieved in priority order:
* - {@link _SERVER_ADDRESS},
* - {@link SEMATTRS_NET_PEER_NAME},
* - {@link _SERVER_SOCKET_ADDRESS}
* - {@link SEMATTRS_DB_CONNECTION_STRING}-Hostname
* </pre>
*
* <pre>
* {port} attribute is retrieved in priority order:
* - {@link _SERVER_PORT},
* - {@link SEMATTRS_NET_PEER_PORT},
* - {@link _SERVER_SOCKET_PORT}
* - {@link SEMATTRS_DB_CONNECTION_STRING}-Port
* </pre>
*
* If address is not present, neither RemoteResourceType nor RemoteResourceIdentifier will be
* provided.
*/
private static getDbConnection;
private static buildDbConnection;
private static buildDbConnectionString;
private static escapeDelimiters;
/**
* Check if the span represents a Lambda Invoke operation.
*/
private static isLambdaInvokeOperation;
/** Span kind is needed for differentiating metrics in the EMF exporter */
private static setSpanKindForService;
private static setSpanKindForDependency;
private static setRemoteDbUser;
private static getRemoteService;
private static getRemoteOperation;
/**
* If no db.operation attribute provided in the span, we use db.statement to compute a valid
* remote operation in a best-effort manner. To do this, we take the first substring of the
* statement and compare to a regex list of known SQL keywords. The substring length is determined
* by the longest known SQL keywords.
*/
private static getDBStatementRemoteOperation;
private static logUnknownAttribute;
}
//# sourceMappingURL=aws-metric-attribute-generator.d.ts.map