Merge branch 'main' into ja/improve-collection-ttl-docs

docs/cache/develop/api-reference/collection-ttl.md

@@ -5,11 +5,19 @@ title: CollectionTTL API reference
 description: Learn how to interact with the CollectionTTL object in Momento Cache.
 ---
 
+import { SdkExampleTabs } from "@site/src/components/SdkExampleTabs";
+// This import is necessary even though it looks like it's un-used; The inject-example-code-snippet
+// plugin will transform instances of SdkExampleTabs to SdkExampleTabsImpl
+import { SdkExampleTabsImpl } from "@site/src/components/SdkExampleTabsImpl";
+
 # CollectionTTL object API reference
 
-This object is passed into API methods to say whether a TTL should be updated and if so, what the new TTL value should be.
+The CollectionTtl type is used when performing write operations on a collection.
+
+Sometimes, when you update a collection, you want to refresh the TTL. Other times you want to keep the TTL the same. The
+CollectionTtl parameter allows you to specify this behavior.
 
-This tries to make the process more intuitive by providing named constructors and copiers for various situations.
+The default behavior is that the collection TTL is modified whenever a write operation occurs.
 
 See [Expire Data with TTL](./../../learn/how-it-works/expire-data-with-ttl.md) for more information on how TTL works with Momento Cache.
 
@@ -28,11 +36,32 @@ You cannot provide a CollectionTTL object when performing a read operation like
 
 :::
 
-## Common method behaviors
+## Default Behavior
 
-- If a CollectionTTL is not passed in a function call, a default value of `CollectionTtl.fromCacheTtl()` will be used. This value is the TTL configured on the cache client. 
+- The `CollectionTtl` parameter is optional for all collection write operations.
+- If a CollectionTTL is not specified, a default value of `CollectionTtl.fromCacheTtl()` will be used. This value is the default TTL configured on the cache client. 
 - The TTL for the collection will be refreshed any time the collection is modified.
 
+## Examples
+
+If you need a behavior other than the default, you can provide a CollectionTtl object for any collection write operation.
+
+To specify an explicit TTL to refresh the collection to on a write operation, you can use `CollectionTtl.of()`:
+
+<SdkExampleTabs snippetId={'API_CollectionTtlOf'} />
+
+This is a convenience method that is equivalent to calling the constructor directly:
+
+<SdkExampleTabs snippetId={'API_CollectionTtlNew'} />
+
+If you want to specify a TTL that is only set when the collection is created, but not refreshed on subsequent writes, you can use `withNoRefreshTtlOnUpdates()`:
+
+<SdkExampleTabs snippetId={'API_CollectionTtlOfNoRefresh'} />
+
+This is also a convenience method that is equivalent to calling the constructor directly:
+
+<SdkExampleTabs snippetId={'API_CollectionTtlNewNoRefresh'} />
+
 ## Constructor parameters
 
 - ttl: duration - (optional)

docs/cache/develop/api-reference/dictionary-collections.md

@@ -15,6 +15,13 @@ This page details the Momento API methods for the [dictionary collection data ty
 
 <img src="/img/dictionary-collections.jpg" width="90%" alt="a technical illustration of stacks of books. some dusty, so not. All collected into groups." />
 
+
+:::info
+
+Momento collection types use a [CollectionTTL](./collection-ttl.md) to specify their TTL behavior. This is an optional argument for all "write" operations.
+
+:::
+
 ## Dictionary methods
 
 ### DictionaryFetch

docs/cache/develop/api-reference/http-api.md

@@ -31,7 +31,7 @@ To access the Momento HTTP API, use one of the following endpoints in the region
 |---|----------------|--------------------------------------------------------------|
 | 1 | us-west-2      | https://api.cache.cell-4-us-west-2-1.prod.a.momentohq.com    |
 | 2 | us-east-1      | https://api.cache.cell-us-east-1-1.prod.a.momentohq.com      |
-| 3 | us-east-2      | https://api.cache.cell-us-east-2-1.prod.a.momentohq.com      |
+| 3 | us-east-2      | https://api.cache.cell-1-us-east-2-1.prod.a.momentohq.com    |
 | 4 | ap-northeast-1 | https://api.cache.cell-ap-northeast-1-1.prod.a.momentohq.com |
 | 5 | eu-west-1      | https://api.cache.cell-1-eu-west-1-1.prod.a.momentohq.com    |
 | 6 | ap-south-1     | https://api.cache.cell-1-ap-south-1-1.prod.a.momentohq.com   |

docs/cache/develop/api-reference/list-collections.md

@@ -17,6 +17,12 @@ This page details the Momento API methods for the [list collection data types](.
 
 ![a technical illustration of a scroll with lists of information. All collected into groups.](@site/static/img/list-collections.jpg)
 
+:::info
+
+Momento collection types use a [CollectionTTL](./collection-ttl.md) to specify their TTL behavior. This is an optional argument for all "write" operations.
+
+:::
+
 ## List methods
 
 ### ListFetch

docs/cache/develop/api-reference/set-collections.md

@@ -16,6 +16,12 @@ A set is a collection of elements, but each element can appear only once and ord
 
 ![a diagram of luggage as sets, but in any old order and not organized at all.](@site/static/img/sets.jpg)
 
+:::info
+
+Momento collection types use a [CollectionTTL](./collection-ttl.md) to specify their TTL behavior. This is an optional argument for all "write" operations.
+
+:::
+
 Example: if your set contains `[1, 2, 3]` and you add 2, the set remains `[1, 2, 3].`
 
 See [Sets](./../basics/datatypes.md#set-collections) for more information on their usage.

docs/cache/develop/api-reference/sorted-set-collections.md

@@ -16,6 +16,12 @@ A sorted set in Momento Cache is a collection of unique elements with a value (S
 
 ![A diagram of luggage as sets, but organized and stacked nicely.](@site/static/img/sorted-sets.jpg)
 
+:::info
+
+Momento collection types use a [CollectionTTL](./collection-ttl.md) to specify their TTL behavior. This is an optional argument for all "write" operations.
+
+:::
+
 ## Sorted set methods
 
 ### SortedSetPutElement

docs/cache/develop/authentication/api-keys.md

@@ -69,6 +69,8 @@ When creating an API key, you have the option to create one that never expires a
 
 The Momento console offers several pre-configured options for expiration ranges or you can select your own date. Just remember to create a new API key and rotate it in your application before it expires to prevent outages!
 
+Momento provides an example of an automatic API key rotation lambda for your convenience [here](https://github.com/momentohq/auth-token-refresh-lambda).
+
 ## Use cases
 
 For shorter-lived authentication use cases, with targeted permission scopes, consider using [Momento tokens](./tokens.md).

docs/cache/develop/integrations/unity-integration.md

@@ -17,7 +17,7 @@ Momento Topics is a serverless approach to real-time communication that allows c
 Download the [Unity 2022 LTS release](https://unity.com/releases/lts). In writing this tutorial, we specifically used Unity 2022.3.9f1 but any Unity 2022 LTS release should work.
 
 ### Momento
-While waiting for Unity to download and install, you can configure the Momento side of things using the [Momento console](https://console.gomomento.com). 
+While waiting for Unity to download and install, you can configure the Momento side of things using the [Momento console](https://console.gomomento.com). Note that this step may be unnecessary if you are already using a [Token Vending Machine](https://github.com/momentohq/client-sdk-javascript/tree/main/examples/nodejs/token-vending-machine) (see `MomentoTopicsDemo-TokenVendingMachine.unity` in [Example Scenes](#example-scenes) below for more information).
 
 1. You can create an account in the console by providing your email address or linking an existing Google or GitHub account. 
 2. Once you've logged into the console, click the `Create Cache` button on the top right of the page:
@@ -79,15 +79,21 @@ The MessagingCanvas also has an emoji button that allows the user to view availa
 
 A helper C# script `EmojiHelper.cs` is used to handle the emoji insertion.
 
-### Understanding the C# script that subscribes to the Momento Topic
+### Setting up the C# script that subscribes to the Momento Topic
 In our example code, the magic happens in `Assets/TopicsTest.cs`, which is based upon the [Momento .NET SDK Topic Example](https://github.com/momentohq/client-sdk-dotnet/tree/main/examples/TopicExample).
 
-The first thing we need to do is to let our C# script know about the API key we created above in the [Momento Prerequisite](#momento) step. Following the [Momento .NET SDK Topic Example](https://github.com/momentohq/client-sdk-dotnet/tree/main/examples/TopicExample), we can either grab the API key from an environment variable or by hard-coding it in our code (note that hard-coding your API key in code is NOT recommended but can be used for testing purposes, if necessary):
+The first thing we need to do is to let our C# script know about the API key we created above in the [Momento Prerequisite](#momento) step. Following the [Momento .NET SDK Topic Example](https://github.com/momentohq/client-sdk-dotnet/tree/main/examples/TopicExample), we can either grab the API key from an environment variable or hard-code the API key in our code (note that hard-coding your API key in code is NOT recommended but can be used for testing purposes, if necessary; an alternative approach using a [Token Vending Machine](https://github.com/momentohq/client-sdk-javascript/tree/main/examples/nodejs/token-vending-machine) is described below in [Example Scenes](#example-scenes)):
 - To set the environment variable in Windows, click the Windows Start button, search for "environment" and click on "Edit the system environment variables." Then click on "Environment Variables" and ensure the `MOMENTO_AUTH_TOKEN` environment variable is set. You may need to restart Unity to get it to recognize your newly created environment variable.
-- To hard-code the API key in C# script, copy and paste your API key into `Assets/TopicsTest.cs` replacing `ADD_YOUR_TOKEN_HERE` in the `ReadAuthToken()` function.
+- To hard-code the API key in a C# script, copy and paste your API key into `Assets/TopicsTest.cs` replacing `ADD_YOUR_TOKEN_HERE` in the `ReadAuthToken()` function.
 
 After the API key is appropriately set, you can go ahead and click on the "Play" button in the Unity Editor to test it out! 
 
+### Example Scenes
+In the example code, we provide three example Unity scenes, showcasing various ways to integrate the Momento SDK with Unity:
+- `MomentoTopicsDemo.unity` (using `TopicsTest.cs`): utilizes `Task.Run()` to run the subscription to the Momento Topic in a background thread. This is the approach descirbed above.
+- `MomentoTopicsDemo-Coroutine.unity` (using `TopicsTestCoroutine.cs`): utilizes Unity Coroutines to run the subscription asyncronously in the main thread.
+- `MomentoTopicsDemo-TokenVendingMachine.unity` (using `TopicsTestTokenVendingMachine.cs`): utilizes the example [Momento Token Vending Machine](https://github.com/momentohq/client-sdk-javascript/tree/main/examples/nodejs/token-vending-machine) to obtain a temporary, restricted scope Momento auth token. This is beneficial because (1) we no longer need to hard-code in a specific auth token into the app, and (2) we can utilize a `tokenId` embedded in the Topics message to more securely know which client/username sent a specific message. Note that you'll need to explicitly setup the Token Vending Machine separately and then specify its URL via the `tokenVendingMachineURL` variable specified in `TopicsTestTokenVendingMachine.cs`.
+
 ## Conclusion
 
 In conclusion, to integrate Momento with Unity is as simple as downloading the latest [MomentoSdkUnity release .zip file](https://github.com/momentohq/client-sdk-dotnet/releases) and unzipping it anywhere within your Unity `Assets` folder. In this tutorial, we took it a step further and demonstrated how to set up a simple chat user interface that connects to a Momento Topic for easy publishing of messages and subscribing to messages. 

docs/cache/develop/sdks/dotnet/cheat-sheet.mdx

@@ -0,0 +1,68 @@
+---
+sidebar_position: 1
+sidebar_label: Cache Cheat Sheet
+sidebar_class_name: sidebar-item-dotnet
+title: Cheat sheet for .NET SDK
+description: Get started really quickly coding using the .NET SDK with Momento Cache
+---
+
+import { SdkExampleCodeBlock } from "@site/src/components/SdkExampleCodeBlock";
+// This import is necessary even though it looks like it's un-used; The inject-example-code-snippet
+// plugin will transform instances of SdkExampleCodeBlock to SdkExampleCodeBlockImpl
+import { SdkExampleCodeBlockImpl } from "@site/src/components/SdkExampleCodeBlockImpl";
+
+# Cheat sheet for .NET with Momento Cache
+
+If you need to get going quickly with .NET and Momento Cache, this page contains the basic API calls you'll need. [Check the .NET SDK examples](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples) for complete, working examples including build configuration files.
+
+## Install the Momento client library
+
+Install the client library in an existing .NET project:
+
+```cli
+dotnet add package Momento.Sdk
+```
+
+## Set up your API key
+
+You'll need a Momento API key to authenticate with Momento.  You can get one from the [Momento Web Console](https://console.gomomento.com/caches).
+Once you have your API key, store it in an environment variable so that the Momento client can consume it:
+
+```
+export MOMENTO_API_KEY=<your Momento API key here>
+```
+
+**Note**: it is best practice to put the API key into something like AWS Secret Manager or GCP Secret Manager instead of an environment variable for enhanced security, but we are using one here for demo purposes.
+
+## Import libraries and create a CacheClient object
+[This example file](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples/MomentoUsage/Program.cs) pulls in the necessary imports, reads the API key from an environment variable, and instantiates the CacheClient that is used to interact with a cache.
+
+## Create a new cache in Momento Cache
+Use this function to create a new cache in your account.
+
+<SdkExampleCodeBlock language={'csharp'} snippetId={'API_CreateCache'} />
+
+## List the names of existing caches in your account
+A simple list of the names of caches for the account.
+
+<SdkExampleCodeBlock language={'csharp'} snippetId={'API_ListCaches'} />
+
+## Write an item to a cache
+A simple example of doing a set operation. In the client.set call, the TTL is optional. If you did pass it in, this would override the default TTL value set with the client connection object.
+
+<SdkExampleCodeBlock language={'csharp'} snippetId={'API_Set'} />
+
+## Read an item from a cache
+This is an example of a simple read operation to get an item from a cache.
+
+<SdkExampleCodeBlock language={'csharp'} snippetId={'API_Get'} />
+
+## Running the code
+
+You can find complete, working examples in the [csharp SDK GitHub repo examples directory](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples).
+
+:::info
+Beyond these basic API calls check out the [API reference page](/cache/develop/api-reference/index.mdx) for more information on the full assortment of Momento API calls.
+
+Check out this example code for [more advanced calls](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples/MomentoApplication/Program.cs).
+:::

docs/cache/develop/sdks/dotnet/index.md

@@ -24,9 +24,9 @@ The source code can be found on GitHub: [momentohq/client-sdk-dotnet](https://gi
 
 ## Resources
 
-- COMING SOON: .NET SDK Cheat Sheet
+- [.NET SDK Cheat Sheet](./cheat-sheet.mdx)
 - [.NET SDK Examples](https://github.com/momentohq/client-sdk-dotnet/blob/main/examples/README.md): working example projects that illustrate how to use the .NET SDK
-- COMING SOON: Observability: Logging and Client-side Metrics with the .NET SDK
+- [.NET SDK Observability](./observability.mdx): Logging and Client-side Metrics with the .NET SDK
 - COMING SOON: Taking your code to prod: Configuration and Error handling in the .NET SDK
 
 ## Integrations

docs/cache/develop/sdks/dotnet/observability.mdx

@@ -0,0 +1,68 @@
+---
+sidebar_position: 2
+sidebar_label: Observability
+sidebar_class_name: sidebar-item-dotnet
+title: Observability for .NET SDK
+description: Instrument your Momento-enabled .NET code with Logs, Metrics, and Traces
+---
+
+import { SdkExampleCodeBlock } from "@site/src/components/SdkExampleCodeBlock";
+// This import is necessary even though it looks like it's un-used; The inject-example-code-snippet
+// plugin will transform instances of SdkExampleCodeBlock to SdkExampleCodeBlockImpl
+import { SdkExampleCodeBlockImpl } from "@site/src/components/SdkExampleCodeBlockImpl";
+
+# Observability with Momento in .NET
+
+## Logging
+
+Our goal for all of the Momento SDKs is to make sure that developers can direct Momento log output to the same destination that they are using for the rest of their application logs; therefore, we aim to be compatible with all of the popular logging frameworks for a given programming language.
+
+The .NET SDK uses the [`ILoggerFactory` and `ILogger` interfaces](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line) so that logs can be written to the desired destination by configuring the appropriate logging providers. 
+
+As long as your preferred logger implements the `ILogger` interface, you can pass the logger into your Momento configuration objects. You can also use your preferred logger in any custom middleware implementation you write ([example here](https://github.com/momentohq/client-sdk-dotnet/blob/main/src/Momento.Sdk/Config/Middleware/LoggingMiddleware.cs)).
+
+Once configured, you should see log messages in your logging environment that look like this:
+```
+[1685649962168] INFO (CacheClient/4386 on mycomputer.local): Creating Momento CacheClient
+[1685649962168] INFO (ControlClient/4386 on mycomputer.local): Creating cache: test-cache
+```
+
+## Metrics
+Metrics are measurements that provide quantitative information about system performance and behavior. They are numerical values captured and recorded over regular intervals, providing statistical data to aid in understanding the trends and patterns in a system.
+
+For Momento, specifically, you might want to capture client-side metrics on the number of requests made, their duration, request or response size, or failure rates. 
+
+The most straightforward way to emit these metrics is to use one of the `ExperimentalMetricsMiddleware` classes. These classes emit metrics in JSON format:
+
+```
+(Momento: _ExperimentalMetricsLoggingMiddleware): 
+{
+  "momento": {
+    "numActiveRequestsAtStart": 1,
+    "numActiveRequestsAtFinish": 1,
+    "requestType": "_GetRequest",
+    "status": 0,
+    "startTime": 1697663118489,
+    "requestBodyTime": 1697663118489,
+    "endTime": 1697663118492,
+    "duration": 3,
+    "requestSize": 32,
+    "responseSize": 2,
+    "connectionID": "0"
+  }
+}
+```
+
+The metrics format is currently considered experimental; in a future release, once the format is considered stable, this class will be renamed to remove the `Experimental` prefix. The two middleware classes available are:
+
+- [`ExperimentalMetricsLoggingMiddleware`](https://github.com/momentohq/client-sdk-dotnet/blob/main/src/Momento.Sdk/Config/Middleware/ExperimentalMetricsLoggingMiddleware.cs): will emit metrics to your chosen logger. WARNING: depending on your request volume, this middleware will produce a high volume of log output. If you are writing logs directly to local disk, be aware of disk usage and make sure you have log rotation / compression enabled via a tool such as `logrotate`.
+- [`ExperimentalMetricsCsvMiddleware`](https://github.com/momentohq/client-sdk-dotnet/blob/main/src/Momento.Sdk/Config/Middleware/ExperimentalMetricsCsvMiddleware.cs): will emit metrics to a CSV file. WARNING: enabling this middleware may have minor performance implications, so enable with caution. Depending on your request volume, the CSV file size may grow quickly, and neither sampling nor file compression / rotation are included at this time.
+
+Log files and CSVs can be analyzed or shared with Momento to diagnose performance issues. You may also direct your logs to an AWS CloudWatch Log Group and create a CloudWatch dashboard to monitor your Momento requests; [an example of launching a Momento metrics dashboard](https://github.com/momentohq/client-sdk-javascript/tree/main/examples/nodejs/lambda-examples/cloudwatch-metrics) and optional example application is available in the Node.js SDK. The example Node.js Lambda and Fargate applications utilize the `ExperimentalMetricsLoggingMiddleware` class and CloudWatch metric filters to populate a dashboard like the one shown below, but you can deploy just the CloudWatch dashboard and populate the graphs with your own .NET application.
+
+![An image of a CloudWatch dashboard with nine graphs populated by Momento metrics](@site/static/img/cloudwatch-dashboard.png)
+
+
+
+
+