From ccd27f7c102bec2371a86bf661fb79649ad293c3 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Fri, 5 Sep 2025 15:53:04 -0700 Subject: [PATCH 1/7] chore: introduce metrics interface in change doc --- .../background.md | 37 +++++++++++++++++++ .../proposal.md | 0 2 files changed, 37 insertions(+) create mode 100644 changes/2025-09-12_introduce-metrics-interface/background.md create mode 100644 changes/2025-09-12_introduce-metrics-interface/proposal.md diff --git a/changes/2025-09-12_introduce-metrics-interface/background.md b/changes/2025-09-12_introduce-metrics-interface/background.md new file mode 100644 index 00000000..7a27a7b3 --- /dev/null +++ b/changes/2025-09-12_introduce-metrics-interface/background.md @@ -0,0 +1,37 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Interacting with a Metrics Interface in the AWS Encryption SDK family of products (Background) + +## Definitions + +### Conventions used in this document + +The key words +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119). + +## Issues and Alternatives + +### collecting metrics from customers? + +Crypto Tools (CT) publishes software libraries. The latest +versions of these libraries have no logging or metrics publishing +to either a local application or to an observability service like AWS CloudWatch. + + + + +### Why should supported libraries collect metrics? + +Metrics collection has long been an outstanding feature request +that has been + +### Default Behavior? + + +### Should Data Plane APIs fail if metrics fail to publish? + + diff --git a/changes/2025-09-12_introduce-metrics-interface/proposal.md b/changes/2025-09-12_introduce-metrics-interface/proposal.md new file mode 100644 index 00000000..e69de29b From 402d3cd4c784c3048cbd175ea6446efaca667472 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Tue, 9 Sep 2025 16:23:29 -0700 Subject: [PATCH 2/7] finished background doc --- .../background.md | 82 +++++++++++++++++-- .../change.md | 39 +++++++++ .../proposal.md | 0 3 files changed, 114 insertions(+), 7 deletions(-) create mode 100644 changes/2025-09-12_introduce-metrics-interface/change.md delete mode 100644 changes/2025-09-12_introduce-metrics-interface/proposal.md diff --git a/changes/2025-09-12_introduce-metrics-interface/background.md b/changes/2025-09-12_introduce-metrics-interface/background.md index 7a27a7b3..b9883bc5 100644 --- a/changes/2025-09-12_introduce-metrics-interface/background.md +++ b/changes/2025-09-12_introduce-metrics-interface/background.md @@ -15,23 +15,91 @@ in this document are to be interpreted as described in ## Issues and Alternatives -### collecting metrics from customers? - Crypto Tools (CT) publishes software libraries. The latest versions of these libraries have no logging or metrics publishing to either a local application or to an observability service like AWS CloudWatch. +As client side encryption libraries emitting metrics must be done carefully as +to avoid accidentally [leaking](https://github.com/aws/aws-encryption-sdk-python/pull/105/files) any information related to the plaintext that could lead to a +loss of customer trust. + +A popular feature request has been for in depth insights into CT libraries. Many customers +ask for suggestions on how to reduce network calls to AWS Key Management Service (AWS KMS) and +followup questions around cache performance. + +CT offers solutions to reduce network calls to AWS KMS through the Caching CMM and the AWS KMS Hierarchical Keyring. +Today, there is no CT solution for customers to extract the performance metrics customers are looking for. +This can lead to frustrating debugging sessions and escalations that +could have been resolved with additional information. + +Recent customer demand has allowed CT to re-evaluate client side metrics to offer +a better customer experience. + +### Issue 1: What will be the default behavior? + +As a client-side encryption library CT should be as cautious as possible. +Customers of CT libraries should be on the driver seat and determine for +themselves if their application could benefit from emitting metrics. +Making that decision for customers can erode customer trust. + +For CT to be comfortable with allowing metrics, CT must consider that +this process must not affect the availability of the consumer of the library. + +#### Opt-In (recommended) + +By not emitting metrics by default existing customer workflows do not change. + +This allows customers to test how their applications behave when they start to emit +metrics. Customers can then ask for updates to the implementations +CT provides or customers can go an implement their own interfaces that are fine-tuned +to their use cases. + +#### Always + +This option implies that CT guarantees that the availability of an application +will not change. Perhaps a bold implication this is ultimately what the customer +will feel like; getting no choice on the matter and opting to not upgrade. +Going from never emitting metrics to always emitting them says to customers +that their application no matter its use case will always benefit from metrics. +Without letting customers make that choice, CT looses hard earned customer trust. + +This also forces customers to make a choice, start collecting metrics and pick up +additional updates CT provides or get stuck in a version of the library that will +become unsupported. + +Additionally, requiring customers to start emitting metrics +almost certainly guarantees a breaking change across supported libraries. + +### Issue 2: Should Data Plane APIs fail if metrics fail to publish? + +#### No (recommended) +Metrics publishing must not impact application availability. +CT should allow for a fail-open approach when metrics fail to publish. +This will prevent metric publishing issues from impacting the +core functionality of the application. -### Why should supported libraries collect metrics? +CT can consider this a two-way door with initially not attempting to retry +to publish failed metrics and add this functionality later on. -Metrics collection has long been an outstanding feature request -that has been +#### Yes -### Default Behavior? +This will become a problem for the libraries and will undoubtedly result +in customer friction and failing adoption rates. +Failing operations due to metrics not being published leaves the availability +of the application to rest on the implementation of the metrics interface. +This should not be the case, metrics should aid the customer application +not restrict it. +### Issue 3: How will customers interact with the libraries to emit metrics? -### Should Data Plane APIs fail if metrics fail to publish? +#### Provide an Interface +Keeping in line with the rest of CT features, a well defined interface with out +of the box implementations should satisfy the feature request. +Out of the box implementations should cover publishing metrics to an +existing observability service like AWS CloudWatch and to the local file system. +These implementations should offer customers a guide into implementing their own +if they wish to do so. diff --git a/changes/2025-09-12_introduce-metrics-interface/change.md b/changes/2025-09-12_introduce-metrics-interface/change.md new file mode 100644 index 00000000..c3f04fb2 --- /dev/null +++ b/changes/2025-09-12_introduce-metrics-interface/change.md @@ -0,0 +1,39 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Adding a Metrics Interface to Crypto Tools Libraries + +## Affected APIs or Client Configurations + +This serves as a reference of all APIs and Client Configurations that this change affects. +This list is not exhaustive. Any downstream consumer of any API or client configuration SHOULD +also be updated as part of this proposed changed. This list contains the obvious changes that +would need to happen in order to support a metrics interface. + +| API/ Configuration | +| --------------------------------------------------------------------------------------- | +| [Encrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/encrypt.md) | +| [Decrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/decrypt.md) | +| [GetEncryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#get-encryption-materials)| +| [DecryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#decrypt-materials)| +| [OnEncrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#onencrypt)| +| [OnDecrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#ondecrypt)| +| [DynamoDB Table Encryption Config](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/specification/dynamodb-encryption-client/ddb-table-encryption-config.md)| + +## Affected Libraries + +| Library | Version Introduced | Implementation | +| -------- | ------------------- | -------------- | +| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy)| +| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy)| +| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy)| + +## Definitions + +### Conventions used in this document + +The key words +"MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in +[RFC 2119](https://tools.ietf.org/html/rfc2119). diff --git a/changes/2025-09-12_introduce-metrics-interface/proposal.md b/changes/2025-09-12_introduce-metrics-interface/proposal.md deleted file mode 100644 index e69de29b..00000000 From 0fcc10e84d5312062fa192e681d104a8172fc7fd Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Sat, 13 Sep 2025 16:23:09 -0700 Subject: [PATCH 3/7] more work on the change doc --- .../change.md | 218 +++++++++++++++++- 1 file changed, 215 insertions(+), 3 deletions(-) diff --git a/changes/2025-09-12_introduce-metrics-interface/change.md b/changes/2025-09-12_introduce-metrics-interface/change.md index c3f04fb2..1a71172b 100644 --- a/changes/2025-09-12_introduce-metrics-interface/change.md +++ b/changes/2025-09-12_introduce-metrics-interface/change.md @@ -1,14 +1,19 @@ [//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." [//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" -# Adding a Metrics Interface to Crypto Tools Libraries +# Adding a Metrics Interface + +***NOTE: This document will be used to gain alignment on +this interface should look like and how it could be integrated with +existing operations. This document will not seek to specify +a Metrics implementation or specify which metrics will be collected +from impacted APIs or configurations.*** ## Affected APIs or Client Configurations This serves as a reference of all APIs and Client Configurations that this change affects. This list is not exhaustive. Any downstream consumer of any API or client configuration SHOULD -also be updated as part of this proposed changed. This list contains the obvious changes that -would need to happen in order to support a metrics interface. +also be updated as part of this proposed changed. | API/ Configuration | | --------------------------------------------------------------------------------------- | @@ -37,3 +42,210 @@ The key words "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +## Summary + +Existing users of Crypto Tools (CT) libraries do no have any insights as to +how the librar(y/ies) behave(s) in their application. +This can lead to frustrating debugging sessions where users +are required to have explicit tests to assert they are using a particular feature +correctly, or if customers are using any of the KMS keyrings users have to have +AWS Cloudwatch open to verify their application is sending values users expect. +This can be seen as a best practice and users may find this a good exercise; +however, CT's libraries do not make debugging an easy task. + +A feature which allows customers to get real-time telemetry of their application's +integration with CT's libraries would be welcomed by users and will deliver on the +"easy to use and hard to misuse" tenet. + +Introducing a new interface that defines the operations that must be +implemented in order to build a specification compliant MetricsAgent. + +## Requirements + +The interface should have three requirements. + +1. MUST be simple. +1. MUST be extensible. + +The following is documented to signify its importance +even though the interface is not able to make this guarantee. +Every implementation of the proposed interface must +ensure the following. + +1. MUST NOT block the application's execution thread. + +## Interface + +### Inputs + +The inputs to the MetricsAgent are groups of related fields, referred to as: + +- [AddDate Input](adddate-input) +- [AddTime Input](#addtime-input) +- [AddCount Input](#addcount-input) +- [AddProperty Input](#addproperty-input) + +#### AddDate Input + +This is the input to the [AddDate](#adddate) behavior. + +The add date input MUST include the following: + +- A label +- A date + +The add date input MAY include the following: + +- A transactionId + +#### AddTime Input + +This is the input to the [AddTime](#addtime) behavior. + +The add time input MUST include the following: + +- A label +- A duration + +The add time input MAY include the following: + +- A transactionId + +#### AddCount Input + +This is the input to the [AddCount](#addcount) behavior. + +The add count input MUST include the following: + +- A label +- A date + +The add count input MAY include the following: + +- A transactionId + +#### AddProperty Input + +This is the input to the [AddProperty](#addproperty) behavior. + +The add property input MUST include the following: + +- A label +- A value + +The add property input MAY include the following: + +- a transactionId + +### Behaviors + +The MetricsAgent Interface MUST support the following behaviors: + +- [AddDate](#adddate) +- [AddTime](#addtime) +- [AddCount](#addcount) +- [AddProperty](#addproperty) + + +#### AddDate + + +#### AddTime + + +#### AddCount + + +#### AddProperty + + +## Points of Integration + + +## Proposed Smithy Model +```smithy +use aws.polymorph#extendable + +@extendable +resource MetricsLogger { + operations: [ + AddDate, + AddTime, + AddCount, + AddProperty + ] +} + +// Operations for different metric types +operation AddDate { + input: AddDateInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddTime { + input: AddTimeInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddCount { + input: AddCountInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddProperty { + input: AddPropertyInput, + output: AddOutput, + errors: [MetricsPutError] +} + +// Input structures for each operation with flattened values +structure AddDateInput { + @required + label: String, + @required + date: Timestamp, + transactionId: String +} + +structure AddTimeInput { + @required + label: String, + @required + duration: Long, // Duration in milliseconds + transactionId: String +} + +structure AddCountInput { + @required + label: String, + @required + count: Long, + transactionId: String +} + +structure AddPropertyInput { + @required + label: String, + @required + value: String, + transactionId: String +} + +// Common output structure +structure AddOutput {} + +// Error structure +@error("client") +structure MetricsPutError { + @required + message: String +} + +@aws.polymorph#reference(resource: MetricsLogger) +structure MetricsLoggerReference {} + +``` From 97380ef0d300d3fa1fcc750b25bcc8e435128b82 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Sun, 14 Sep 2025 14:54:24 -0700 Subject: [PATCH 4/7] add metrics-agent interface file --- framework/metrics-agent.md | 126 +++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 framework/metrics-agent.md diff --git a/framework/metrics-agent.md b/framework/metrics-agent.md new file mode 100644 index 00000000..5f1c9027 --- /dev/null +++ b/framework/metrics-agent.md @@ -0,0 +1,126 @@ +[//]: # "Copyright Amazon.com Inc. or its affiliates. All Rights Reserved." +[//]: # "SPDX-License-Identifier: CC-BY-SA-4.0" + +# Metrics Agent Interface + +## Version + +1.0.0 + +### Changelog + +- 1.0.0 + + - Initial record + +## Implementations + +| Library | Version Introduced | Implementation | +| -------- | ------------------- | -------------- | +| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy)| +| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy)| +| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy)| + +## Overview + +The Metrics Agent defines defines operations that allow messages +to be published to a destination. +The Metrics Agent interface describes the interface that all +Metrics Agents MUST implement. + +## Definitions + +### Conventions used in this document + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" +in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). + +## Supported Metrics Agents + +T.B.D + +Note: A user MAY create their own custom Metrics Agent. + +## Interface + +### Inputs + +The inputs to the MetricsAgent are groups of related fields, referred to as: + +- [AddDate Input](adddate-input) +- [AddTime Input](#addtime-input) +- [AddCount Input](#addcount-input) +- [AddProperty Input](#addproperty-input) + +#### AddDate Input + +This is the input to the [AddDate](#adddate) behavior. + +The add date input MUST include the following: + +- A label +- A date + +The add date input MAY include the following: + +- A transactionId + +#### AddTime Input + +This is the input to the [AddTime](#addtime) behavior. + +The add time input MUST include the following: + +- A label +- A duration + +The add time input MAY include the following: + +- A transactionId + +#### AddCount Input + +This is the input to the [AddCount](#addcount) behavior. + +The add count input MUST include the following: + +- A label +- A date + +The add count input MAY include the following: + +- A transactionId + +#### AddProperty Input + +This is the input to the [AddProperty](#addproperty) behavior. + +The add property input MUST include the following: + +- A label +- A value + +The add property input MAY include the following: + +- a transactionId + +### Behaviors + +The MetricsAgent Interface MUST support the following behaviors: + +- [AddDate](#adddate) +- [AddTime](#addtime) +- [AddCount](#addcount) +- [AddProperty](#addproperty) + + +#### AddDate + + +#### AddTime + + +#### AddCount + + +#### AddProperty From a42a891a2e6fb4f8be95692e4279b0a60bf36a81 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Sun, 14 Sep 2025 16:44:33 -0700 Subject: [PATCH 5/7] finish first draft of metrics interface --- .../change.md | 237 ++++++------------ framework/metrics-agent.md | 156 ++++++++++-- 2 files changed, 214 insertions(+), 179 deletions(-) diff --git a/changes/2025-09-12_introduce-metrics-interface/change.md b/changes/2025-09-12_introduce-metrics-interface/change.md index 1a71172b..1163d590 100644 --- a/changes/2025-09-12_introduce-metrics-interface/change.md +++ b/changes/2025-09-12_introduce-metrics-interface/change.md @@ -75,177 +75,94 @@ ensure the following. 1. MUST NOT block the application's execution thread. -## Interface - -### Inputs - -The inputs to the MetricsAgent are groups of related fields, referred to as: - -- [AddDate Input](adddate-input) -- [AddTime Input](#addtime-input) -- [AddCount Input](#addcount-input) -- [AddProperty Input](#addproperty-input) - -#### AddDate Input - -This is the input to the [AddDate](#adddate) behavior. - -The add date input MUST include the following: - -- A label -- A date - -The add date input MAY include the following: - -- A transactionId - -#### AddTime Input - -This is the input to the [AddTime](#addtime) behavior. - -The add time input MUST include the following: - -- A label -- A duration - -The add time input MAY include the following: - -- A transactionId - -#### AddCount Input - -This is the input to the [AddCount](#addcount) behavior. - -The add count input MUST include the following: - -- A label -- A date - -The add count input MAY include the following: - -- A transactionId - -#### AddProperty Input - -This is the input to the [AddProperty](#addproperty) behavior. - -The add property input MUST include the following: - -- A label -- A value - -The add property input MAY include the following: - -- a transactionId - -### Behaviors - -The MetricsAgent Interface MUST support the following behaviors: - -- [AddDate](#adddate) -- [AddTime](#addtime) -- [AddCount](#addcount) -- [AddProperty](#addproperty) - - -#### AddDate - - -#### AddTime - - -#### AddCount - - -#### AddProperty - - ## Points of Integration +To collect metrics across CT's library stack multiple points of integration +are needed in order to collect metrics across CT's libraries. +Generally, CT's libraries work as follows: + +*Note: Not every Client supports the Material Provider Library. +The Diagram below assumes it to help the mental model.* + +```mermaid +sequenceDiagram + participant Client + box Material Provider Library + participant CMM + participant Keyring + end + loop Content Encryption + Client->>Client: Content Encryption + end + Client<<->>CMM: GetEncryption/Decryption Materials + CMM<<->>Keyring: OnEncrypt/OnDecrypt +``` -## Proposed Smithy Model -```smithy -use aws.polymorph#extendable - -@extendable -resource MetricsLogger { - operations: [ - AddDate, - AddTime, - AddCount, - AddProperty - ] -} - -// Operations for different metric types -operation AddDate { - input: AddDateInput, - output: AddOutput, - errors: [MetricsPutError] -} - -operation AddTime { - input: AddTimeInput, - output: AddOutput, - errors: [MetricsPutError] -} +To optionally emit metrics from a top level client, +all customer facing APIs MUST be changed to optionally accept +a Metrics Agent. This will allow customers to define and supply one top +level Metrics Agent; this agent will get plumbed throughout CT's stack. + +For example, in the ESDK for Java this would look like: +```java +final AwsCrypto crypto = AwsCrypto.builder().build(); +// Create a Keyring +final MaterialProviders matProv = + MaterialProviders.builder() + .MaterialProvidersConfig(MaterialProvidersConfig.builder().build()) + .build(); + +final IKeyring rawAesKeyring = matProv.CreateRawAesKeyring(keyringInput); +final Map encryptionContext = + Collections.singletonMap("ExampleContextKey", "ExampleContextValue"); + +// Create a Metrics Agent +final IMetricsAgent metrics = matProv.CreateSimpleMetricsAgent(metricsAgentInput); +// 4. Encrypt the data +final CryptoResult encryptResult = + crypto.encryptData(rawAesKeyring, metrics, EXAMPLE_DATA, encryptionContext); +final byte[] ciphertext = encryptResult.getResult(); +``` -operation AddCount { - input: AddCountInput, - output: AddOutput, - errors: [MetricsPutError] -} +This change will allow Crypto Tools to introduce a Metrics Agent in a +non-breaking way as the Metrics Agent will be an optional parameter +at customer facing API call sites. -operation AddProperty { - input: AddPropertyInput, - output: AddOutput, - errors: [MetricsPutError] -} +Currently, the ESDK client APIs models are defined [here](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy#L60-L126). +This change would see that the client APIs be changed as follows: -// Input structures for each operation with flattened values -structure AddDateInput { - @required - label: String, +```diff +structure EncryptInput { @required - date: Timestamp, - transactionId: String -} + plaintext: Blob, -structure AddTimeInput { - @required - label: String, - @required - duration: Long, // Duration in milliseconds - transactionId: String -} + encryptionContext: aws.cryptography.materialProviders#EncryptionContext, -structure AddCountInput { - @required - label: String, - @required - count: Long, - transactionId: String -} + // One of keyring or CMM are required + materialsManager: aws.cryptography.materialProviders#CryptographicMaterialsManagerReference, + keyring: aws.cryptography.materialProviders#KeyringReference, -structure AddPropertyInput { - @required - label: String, - @required - value: String, - transactionId: String -} + algorithmSuiteId: aws.cryptography.materialProviders#ESDKAlgorithmSuiteId, -// Common output structure -structure AddOutput {} + frameLength: FrameLength, -// Error structure -@error("client") -structure MetricsPutError { ++ metricsAgent: aws.cryptography.materialProviders#MetricsAgentReference +} +... +structure DecryptInput { @required - message: String + ciphertext: Blob, + + // One of keyring or CMM are required + materialsManager: aws.cryptography.materialProviders#CryptographicMaterialsManagerReference, + keyring: aws.cryptography.materialProviders#KeyringReference, + //= aws-encryption-sdk-specification/client-apis/keyring-interface.md#onencrypt + //= type=implication + //# The following inputs to this behavior MUST be OPTIONAL: + // (blank line for duvet) + //# - [Encryption Context](#encryption-context) + encryptionContext: aws.cryptography.materialProviders#EncryptionContext, + ++ metricsAgent: aws.cryptography.materialProviders#MetricsAgentReference } - -@aws.polymorph#reference(resource: MetricsLogger) -structure MetricsLoggerReference {} - -``` +``` \ No newline at end of file diff --git a/framework/metrics-agent.md b/framework/metrics-agent.md index 5f1c9027..7a0f61d3 100644 --- a/framework/metrics-agent.md +++ b/framework/metrics-agent.md @@ -3,6 +3,8 @@ # Metrics Agent Interface +*NOTE: Still in draft but in a state to receive feedback on 9-15-2025* + ## Version 1.0.0 @@ -35,9 +37,38 @@ Metrics Agents MUST implement. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119). -## Supported Metrics Agents +### label + +A label is a string that is used +as a an attribute name to aggregate +measurements. A label can be used to +add a dimension to the Metrics Agent + +### date + +A date is a value in milliseconds since epoch. + +### duration + +A duration is a value in milliseconds + +### count + +A count is an Long value + +### value -T.B.D +A value is a string that is used to attach +context to a particular label. + +### transactionId + +A transactionId is a string that +is used to coalasce multiple metric requests +for a given client request. + + +## Supported Metrics Agents Note: A user MAY create their own custom Metrics Agent. @@ -47,7 +78,7 @@ Note: A user MAY create their own custom Metrics Agent. The inputs to the MetricsAgent are groups of related fields, referred to as: -- [AddDate Input](adddate-input) +- [AddDate Input](#adddate-input) - [AddTime Input](#addtime-input) - [AddCount Input](#addcount-input) - [AddProperty Input](#addproperty-input) @@ -58,12 +89,12 @@ This is the input to the [AddDate](#adddate) behavior. The add date input MUST include the following: -- A label -- A date +- A [label](#label) +- A [date](#date) The add date input MAY include the following: -- A transactionId +- A [transactionId](#transactionid) #### AddTime Input @@ -71,12 +102,12 @@ This is the input to the [AddTime](#addtime) behavior. The add time input MUST include the following: -- A label -- A duration +- A [label](#label) +- A [duration](#duration) The add time input MAY include the following: -- A transactionId +- A [transactionId](#transactionid) #### AddCount Input @@ -84,12 +115,12 @@ This is the input to the [AddCount](#addcount) behavior. The add count input MUST include the following: -- A label -- A date +- A [label](#label) +- A [count](#count) The add count input MAY include the following: -- A transactionId +- A [transactionId](#transactionid) #### AddProperty Input @@ -97,12 +128,12 @@ This is the input to the [AddProperty](#addproperty) behavior. The add property input MUST include the following: -- A label -- A value +- A [label](#label) +- A [value](#value) The add property input MAY include the following: -- a transactionId +- A [transactionId](#transactionid) ### Behaviors @@ -113,14 +144,101 @@ The MetricsAgent Interface MUST support the following behaviors: - [AddCount](#addcount) - [AddProperty](#addproperty) - #### AddDate - +Used to record a specific time value with the same metric name. #### AddTime - +Used to aggregate a sum from multiple time values with the same metric name. #### AddCount - +Used to aggregate a sum from multiple count values with the same metric name. #### AddProperty +Used to add context/metadata in the form of a key-value pair related to a Metrics instance + +## Proposed Smithy Model +```smithy +use aws.polymorph#extendable + +@extendable +resource MetricsAgent { + operations: [ + AddDate, + AddTime, + AddCount, + AddProperty + ] +} + +// Operations for different metric types +operation AddDate { + input: AddDateInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddTime { + input: AddTimeInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddCount { + input: AddCountInput, + output: AddOutput, + errors: [MetricsPutError] +} + +operation AddProperty { + input: AddPropertyInput, + output: AddOutput, + errors: [MetricsPutError] +} + +// Input structures for each operation with flattened values +structure AddDateInput { + @required + label: String, + @required + date: Timestamp, + transactionId: String +} + +structure AddTimeInput { + @required + label: String, + @required + duration: Long, // Duration in milliseconds + transactionId: String +} + +structure AddCountInput { + @required + label: String, + @required + count: Long, + transactionId: String +} + +structure AddPropertyInput { + @required + label: String, + @required + value: String, + transactionId: String +} + +// Common output structure +structure AddOutput {} + +// Error structure +@error("client") +structure MetricsPutError { + @required + message: String +} + +@aws.polymorph#reference(resource: MetricsAgent) +structure MetricsAgentReference {} + +``` \ No newline at end of file From 61fe175542527c0a83356167da6e2260e0bd4d27 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Sun, 14 Sep 2025 16:49:20 -0700 Subject: [PATCH 6/7] prettify --- .../change.md | 47 ++++++++++--------- framework/metrics-agent.md | 29 +++++++----- 2 files changed, 40 insertions(+), 36 deletions(-) diff --git a/changes/2025-09-12_introduce-metrics-interface/change.md b/changes/2025-09-12_introduce-metrics-interface/change.md index 1163d590..94024b0b 100644 --- a/changes/2025-09-12_introduce-metrics-interface/change.md +++ b/changes/2025-09-12_introduce-metrics-interface/change.md @@ -3,11 +3,11 @@ # Adding a Metrics Interface -***NOTE: This document will be used to gain alignment on +**_NOTE: This document will be used to gain alignment on this interface should look like and how it could be integrated with existing operations. This document will not seek to specify a Metrics implementation or specify which metrics will be collected -from impacted APIs or configurations.*** +from impacted APIs or configurations._** ## Affected APIs or Client Configurations @@ -15,23 +15,23 @@ This serves as a reference of all APIs and Client Configurations that this chang This list is not exhaustive. Any downstream consumer of any API or client configuration SHOULD also be updated as part of this proposed changed. -| API/ Configuration | -| --------------------------------------------------------------------------------------- | -| [Encrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/encrypt.md) | -| [Decrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/decrypt.md) | -| [GetEncryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#get-encryption-materials)| -| [DecryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#decrypt-materials)| -| [OnEncrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#onencrypt)| -| [OnDecrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#ondecrypt)| -| [DynamoDB Table Encryption Config](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/specification/dynamodb-encryption-client/ddb-table-encryption-config.md)| +| API/ Configuration | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Encrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/encrypt.md) | +| [Decrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/client-apis/decrypt.md) | +| [GetEncryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#get-encryption-materials) | +| [DecryptionMaterials](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/cmm-interface.md#decrypt-materials) | +| [OnEncrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#onencrypt) | +| [OnDecrypt](https://github.com/awslabs/aws-encryption-sdk-specification/blob/master/framework/keyring-interface.md#ondecrypt) | +| [DynamoDB Table Encryption Config](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/specification/dynamodb-encryption-client/ddb-table-encryption-config.md) | ## Affected Libraries -| Library | Version Introduced | Implementation | -| -------- | ------------------- | -------------- | -| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy)| -| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy)| -| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy)| +| Library | Version Introduced | Implementation | +| ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy) | +| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy) | +| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy) | ## Definitions @@ -46,7 +46,7 @@ in this document are to be interpreted as described in ## Summary Existing users of Crypto Tools (CT) libraries do no have any insights as to -how the librar(y/ies) behave(s) in their application. +how the librar(y/ies) behave(s) in their application. This can lead to frustrating debugging sessions where users are required to have explicit tests to assert they are using a particular feature correctly, or if customers are using any of the KMS keyrings users have to have @@ -54,7 +54,7 @@ AWS Cloudwatch open to verify their application is sending values users expect. This can be seen as a best practice and users may find this a good exercise; however, CT's libraries do not make debugging an easy task. -A feature which allows customers to get real-time telemetry of their application's +A feature which allows customers to get real-time telemetry of their application's integration with CT's libraries would be welcomed by users and will deliver on the "easy to use and hard to misuse" tenet. @@ -81,17 +81,17 @@ To collect metrics across CT's library stack multiple points of integration are needed in order to collect metrics across CT's libraries. Generally, CT's libraries work as follows: -*Note: Not every Client supports the Material Provider Library. -The Diagram below assumes it to help the mental model.* +_Note: Not every Client supports the Material Provider Library. +The Diagram below assumes it to help the mental model._ ```mermaid sequenceDiagram participant Client - box Material Provider Library + box Material Provider Library participant CMM participant Keyring end - loop Content Encryption + loop Content Encryption Client->>Client: Content Encryption end Client<<->>CMM: GetEncryption/Decryption Materials @@ -104,6 +104,7 @@ a Metrics Agent. This will allow customers to define and supply one top level Metrics Agent; this agent will get plumbed throughout CT's stack. For example, in the ESDK for Java this would look like: + ```java final AwsCrypto crypto = AwsCrypto.builder().build(); // Create a Keyring @@ -165,4 +166,4 @@ structure DecryptInput { + metricsAgent: aws.cryptography.materialProviders#MetricsAgentReference } -``` \ No newline at end of file +``` diff --git a/framework/metrics-agent.md b/framework/metrics-agent.md index 7a0f61d3..3be42a9d 100644 --- a/framework/metrics-agent.md +++ b/framework/metrics-agent.md @@ -3,7 +3,7 @@ # Metrics Agent Interface -*NOTE: Still in draft but in a state to receive feedback on 9-15-2025* +_NOTE: Still in draft but in a state to receive feedback on 9-15-2025_ ## Version @@ -12,22 +12,21 @@ ### Changelog - 1.0.0 - - Initial record ## Implementations -| Library | Version Introduced | Implementation | -| -------- | ------------------- | -------------- | -| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy)| -| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy)| -| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy)| +| Library | Version Introduced | Implementation | +| ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| ESDK | T.B.D | [ESDK.smithy](https://github.com/aws/aws-encryption-sdk/blob/mainline/AwsEncryptionSDK/dafny/AwsEncryptionSdk/Model/esdk.smithy) | +| MPL | T.B.D | [material-provider.smithy](https://github.com/aws/aws-cryptographic-material-providers-library/blob/main/AwsCryptographicMaterialProviders/dafny/AwsCryptographicMaterialProviders/Model/material-provider.smithy) | +| DB-ESDK | T.B.D | [DynamoDbEncryption.smithy](https://github.com/aws/aws-database-encryption-sdk-dynamodb/blob/main/DynamoDbEncryption/dafny/DynamoDbEncryption/Model/DynamoDbEncryption.smithy) | ## Overview The Metrics Agent defines defines operations that allow messages to be published to a destination. -The Metrics Agent interface describes the interface that all +The Metrics Agent interface describes the interface that all Metrics Agents MUST implement. ## Definitions @@ -67,7 +66,6 @@ A transactionId is a string that is used to coalasce multiple metric requests for a given client request. - ## Supported Metrics Agents Note: A user MAY create their own custom Metrics Agent. @@ -145,27 +143,32 @@ The MetricsAgent Interface MUST support the following behaviors: - [AddProperty](#addproperty) #### AddDate + Used to record a specific time value with the same metric name. #### AddTime + Used to aggregate a sum from multiple time values with the same metric name. #### AddCount + Used to aggregate a sum from multiple count values with the same metric name. #### AddProperty + Used to add context/metadata in the form of a key-value pair related to a Metrics instance ## Proposed Smithy Model + ```smithy use aws.polymorph#extendable @extendable resource MetricsAgent { operations: [ - AddDate, - AddTime, - AddCount, + AddDate, + AddTime, + AddCount, AddProperty ] } @@ -241,4 +244,4 @@ structure MetricsPutError { @aws.polymorph#reference(resource: MetricsAgent) structure MetricsAgentReference {} -``` \ No newline at end of file +``` From e95b0f23b5dbc8399cd02ff8e80c7ae9bebecb33 Mon Sep 17 00:00:00 2001 From: Jose Corella Date: Mon, 15 Sep 2025 09:04:46 -0700 Subject: [PATCH 7/7] update --- framework/metrics-agent.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/framework/metrics-agent.md b/framework/metrics-agent.md index 3be42a9d..6235b433 100644 --- a/framework/metrics-agent.md +++ b/framework/metrics-agent.md @@ -156,7 +156,7 @@ Used to aggregate a sum from multiple count values with the same metric name. #### AddProperty -Used to add context/metadata in the form of a key-value pair related to a Metrics instance +Used to add context/metadata in the form of a key-value pair related to a Metrics reference. ## Proposed Smithy Model