Merge pull request #98430 from erhopf/obj-tracking

[CogSvcs] Obj tracking for Speech SDK

Author: ktoliver

articles/cognitive-services/Speech-Service/how-to-track-speech-sdk-memory-usage.md

@@ -0,0 +1,148 @@
+---
+title: How to track Speech SDK memory usage - Speech service
+titleSuffix: Azure Cognitive Services
+description: The Speech Service SDK supports numerous programming languages for speech-to-text and text-to-speech conversion, along with speech translation. This article discusses memory management tooling built into the SDK.
+services: cognitive-services
+author: erhopf
+manager: nitinme
+ms.service: cognitive-services
+ms.subservice: speech-service
+ms.topic: conceptual
+ms.date: 12/10/2019
+ms.author: rhurey
+zone_pivot_groups: programming-languages-set-two
+---
+
+# How to track Speech SDK memory usage
+
+The Speech SDK is based on a native code base that's projected into multiple programming languages through a series of interoperability layers. Each language-specific projection has idiomatically correct features to manage the object lifecycle. Additionally, the Speech SDK includes memory management tooling to track resource usage with object logging and object limits. 
+
+## How to read object logs
+
+If [Speech SDK logging is enabled](how-to-use-logging.md), tracking tags are emitted to enable historical object observation. These tags include: 
+
+* `TrackHandle` or `StopTracking` 
+* The object type
+* The current number of objects that are tracked the type of the object, and the current number being tracked.
+
+Here's a sample log: 
+
+```terminal
+(284): 8604ms SPX_DBG_TRACE_VERBOSE:  handle_table.h:90 TrackHandle type=Microsoft::CognitiveServices::Speech::Impl::ISpxRecognitionResult handle=0x0x7f688401e1a0, ptr=0x0x7f688401e1a0, total=19
+```
+
+## Set a warning threshold
+
+You have the option to create a warning threshold, and if that threshold is exceeded (assuming logging is enabled), a warning message is logged. The warning message contains a dump of all objects in existence along with their count. This information can be used to better understand issues. 
+
+To enable a warning threshold, it must be specified on a `SpeechConfig` object. This object is checked when a new recognizer is created. In the following examples, let's assume that you've created an instance of `SpeechConfig` called `config`:
+
+::: zone pivot="programming-language-csharp"
+
+```csharp
+config.SetProperty("SPEECH-ObjectCountWarnThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-cpp"
+
+```C++
+config->SetProperty("SPEECH-ObjectCountWarnThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-java"
+
+```java
+config.setProperty("SPEECH-ObjectCountWarnThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-python"
+
+```Python
+speech_config.set_property_by_name(“SPEECH-ObjectCountWarnThreshold", "10000")?
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-more"
+
+```ObjectiveC
+[config setPropertyTo:@"10000" byName:"SPEECH-ObjectCountWarnThreshold"];
+```
+
+::: zone-end
+
+> [!TIP]
+> The default value for this property is 10,000.
+
+## Set an error threshold 
+
+Using the Speech SDK, you can set the maximum number of objects allowed at a given time. If this setting is enabled, when the maximum number is hit, attempts to create new recognizer objects will fail. Existing objects will continue to work.
+
+Here's a sample error:
+
+```terminal
+Runtime error: The maximum object count of 500 has been exceeded.
+The threshold can be adjusted by setting the SPEECH-ObjectCountErrorThreshold property on the SpeechConfig object.
+See http://https://docs.microsoft.com/azure/cognitive-services/speech-service/how-to-object-tracking-speech-sdk for more detailed information.
+Handle table dump by ojbect type:
+class Microsoft::CognitiveServices::Speech::Impl::ISpxRecognitionResult 0
+class Microsoft::CognitiveServices::Speech::Impl::ISpxRecognizer 0
+class Microsoft::CognitiveServices::Speech::Impl::ISpxAudioConfig 0
+class Microsoft::CognitiveServices::Speech::Impl::ISpxSpeechConfig 0
+```
+
+To enable an error threshold, it must be specified on a `SpeechConfig` object. This object is checked when a new recognizer is created. In the following examples, let's assume that you've created an instance of `SpeechConfig` called `config`:
+
+::: zone pivot="programming-language-csharp"
+
+```csharp
+config.SetProperty("SPEECH-ObjectCountErrorThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-cpp"
+
+```C++
+config->SetProperty("SPEECH-ObjectCountErrorThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-java"
+
+```java
+config.setProperty("SPEECH-ObjectCountErrorThreshold", "10000");
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-python"
+
+```Python
+speech_config.set_property_by_name(“SPEECH-ObjectCountErrorThreshold", "10000")?
+```
+
+::: zone-end
+
+::: zone pivot="programming-language-more"
+
+```objc
+[config setPropertyTo:@"10000" byName:"SPEECH-ObjectCountErrorThreshold"];
+```
+
+::: zone-end
+
+> [!TIP]
+> The default value for this property is the platform-specific maximum value for a `size_t` data type. A typical recognition will consume between 7 and 10 internal objects.
+
+## Next steps
+
+* [Get your Speech service trial subscription](get-started.md)
+* [Learn how to recognize speech using a microphone](quickstarts/speech-to-text-from-microphone.md)

articles/cognitive-services/Speech-Service/toc.yml

@@ -405,8 +405,11 @@
       href: quickstarts/setup-platform.md?pivots=programming-language-more
   - name: How-to guides
     items:
-    - name: Enable logging
+    - name: How to enable logging
       href: how-to-use-logging.md
+    - name: How to track memory usage
+      href: how-to-track-speech-sdk-memory-usage.md
+      displayName: "memory usage, memory consumption, object logging, object tracking, memory"
   - name: Samples
     items:
     - name: Speech SDK Samples (GitHub)