Skip to content

Commit e086f4d

Browse files
cqfu96cqfu96
committed
New diagnostics logging API
1 parent f22732d commit e086f4d

File tree

7 files changed

+407
-0
lines changed

7 files changed

+407
-0
lines changed

‎articles/ai-services/speech-service/how-to-use-logging.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -171,6 +171,29 @@ void DisableSpeechSdkLogging()
171171
}
172172
```
173173
174+
175+
## Logging with file logger, Memory logger and event logger
176+
177+
::: zone pivot="programming-language-csharp"
178+
[!INCLUDE [C# include](includes/how-to/diagnostics/csharp.md)]
179+
::: zone-end
180+
181+
::: zone pivot="programming-language-cpp"
182+
[!INCLUDE [C++ include](includes/how-to/diagnostics/cpp.md)]
183+
::: zone-end
184+
185+
::: zone pivot="programming-language-java"
186+
[!INCLUDE [Java include](includes/how-to/diagnostics/java.md)]
187+
::: zone-end
188+
189+
::: zone pivot="programming-language-objectivec"
190+
[!INCLUDE [ObjectiveC include](includes/how-to/diagnostics/objectivec.md)]
191+
::: zone-end
192+
193+
::: zone pivot="programming-language-python"
194+
[!INCLUDE [Python include](./includes/how-to/diagnostics/python.md)]
195+
::: zone-end
196+
174197
## Next steps
175198
176199
> [!div class="nextstepaction"]

‎articles/ai-services/speech-service/includes/how-to/diagnostics/cpp.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
author: charles-fu
3+
ms.service: azure-ai-speech
4+
ms.topic: include
5+
ms.date: 03/18/2025
6+
ms.author: changfu001
7+
---
8+
9+
[!INCLUDE [Introduction](intro.md)]
10+
11+
### Samples
12+
13+
```cpp
14+
using namespace Microsoft::CognitiveServices::Speech;
15+
using namespace Microsoft::CognitiveServices::Speech::Diagnostics::Logging;
16+
17+
void FileLoggerWithoutFilters()
18+
{
19+
FileLogger::Start("LogfilePathAndName");
20+
21+
// Other Speech SDK calls
22+
23+
FileLogger::Stop();
24+
}
25+
26+
void FileLoggerWithFilters()
27+
{
28+
std::initializer_list<std::string> filters = { "YourFirstString", "YourSecondString" };
29+
FileLogger::SetFilters(filters);
30+
FileLogger::Start("LogfilePathAndName");
31+
32+
// Other Speech SDK calls
33+
34+
FileLogger::Stop();
35+
FileLogger::SetFilters();
36+
}
37+
38+
void MemoryLoggerWithoutFilters()
39+
{
40+
MemoryLogger::Start();
41+
42+
// Other Speech SDK calls
43+
44+
// At any time (whether logging is stopped) you can dump the traces in memory to a file
45+
MemoryLogger::Dump("LogfilePathAndName");
46+
47+
// Or dump to any stream object that is derived from std::ostream. For example, std::cout
48+
MemoryLogger::Dump(std::cout);
49+
50+
// Or dump to a vector of strings
51+
std::vector<std::string> messages = MemoryLogger::Dump();
52+
53+
MemoryLogger::Stop();
54+
}
55+
56+
void EventLoggerWithoutFilters()
57+
{
58+
std::mutex mtx;
59+
std::vector<std::string> messages;
60+
61+
// Register a callback that will get invoked by Speech SDK on every new log message
62+
EventLogger::SetCallback([&messages, &mtx](std::string message) {
63+
// Store the message for later processing. Better not processing it in the event thread
64+
std::unique_lock<std::mutex> lock(mtx);
65+
messages.push_back(message);
66+
});
67+
68+
// Other Speech SDK calls
69+
70+
// Stop logging by setting an empty callback
71+
EventLogger::SetCallback();
72+
}
73+
```

‎articles/ai-services/speech-service/includes/how-to/diagnostics/csharp.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
author: charles-fu
3+
ms.service: azure-ai-speech
4+
ms.topic: include
5+
ms.date: 03/18/2025
6+
ms.author: changfu001
7+
ms.custom: devx-track-csharp
8+
---
9+
10+
[!INCLUDE [Introduction](intro.md)]
11+
12+
### Samples
13+
14+
```csharp
15+
using Microsoft.CognitiveServices.Speech;
16+
using Microsoft.CognitiveServices.Speech.Diagnostics.Logging;
17+
18+
class Program
19+
{
20+
public static void FileLoggerWithoutFilters()
21+
{
22+
FileLogger.Start("LogfilePathAndName");
23+
24+
// Other Speech SDK calls
25+
26+
FileLogger.Stop();
27+
}
28+
29+
public static void FileLoggerWithFilters()
30+
{
31+
string[] filters = { "YourFirstString", "YourSecondString" };
32+
FileLogger.SetFilters(filters);
33+
FileLogger.Start("LogfilePathAndName");
34+
35+
// Other Speech SDK calls
36+
37+
FileLogger.Stop();
38+
FileLogger.SetFilters();
39+
}
40+
41+
public static void MemoryLoggerWithoutFilters()
42+
{
43+
MemoryLogger.Start();
44+
45+
// Other Speech SDK calls
46+
47+
// At any time (whether logging is stopped) you can dump the traces in memory to a file
48+
MemoryLogger.Dump("LogfilePathAndName");
49+
50+
// Or dump to any object that is derived from System.IO.TextWriter. For example, System.Console.Out
51+
MemoryLogger.Dump(System.Console.Out);
52+
53+
// Or dump to a vector of strings
54+
List<string> messages = MemoryLogger.Dump().ToList<string>();
55+
56+
MemoryLogger.Stop();
57+
}
58+
59+
// These variables and method are used by the EvenLogger sample below.
60+
private static readonly object lockObject = new object();
61+
private static List<string> eventMessages = new List<string>();
62+
private static void OnMessageEvent(object sender, string message)
63+
{
64+
lock (lockObject)
65+
{
66+
// Store the message for later processing. Better not processing it in the event thread
67+
eventMessages.Add(message);
68+
}
69+
}
70+
71+
public static void EventLoggerWithoutFilters()
72+
{
73+
// Subscribe an event that will get invoked by Speech SDK on every new log message
74+
EventLogger.OnMessage += OnMessageEvent;
75+
76+
// Other Speech SDK calls
77+
78+
// Unsubscribe to stop getting events
79+
EventLogger.OnMessage -= OnMessageEvent;
80+
}
81+
}
82+
```

‎articles/ai-services/speech-service/includes/how-to/diagnostics/intro.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
author: charles-fu
3+
ms.service: azure-ai-speech
4+
ms.topic: include
5+
ms.date: 03/18/2025
6+
ms.author: changfu001
7+
---
8+
9+
Starting from version 1.43.0, SDK extends logging mechanism with three types of loggers: `File logger`, `Memory logger` and `Event logger`.
10+
11+
`File logger` is the simplest logging solution and suitable for diagnosing most on-device issues when running Speech SDK.
12+
13+
`Memory logger` is a logging solution that stores log messages in memory. It is suitable for diagnosing issues that occur in a short period of time. For example, if you are running a Speech Recognizer, you may want to dump the memory logger after getting an event indicating recognition was canceled due to some error. The size of the memory buffer is fixed at 2MB and cannot be changed. This is a "ring" buffer, that is, new log strings written replace the oldest ones in the buffer.
14+
15+
`Event logger` is a logging solution that sends log messages to the event handler which is provided by the developer. It is suitable for diagnosing issues when certain new log strings are as soon as available and need for further processing. For example, integrating Speech SDK logs with your existing logging collection system.
16+
17+
`File logger, memory logger and event logger` all have filter mechanism by only logging certain string messages. Also these loggers are process wide constructs. That means that if (for example) you have multiple speech recognizer objects running in parallel, there will be one log file containing interleaved logs lines from all recognizers. You cannot get a separate file logger for each recognizer. Similarly, there will be one
18+
memory buffer containing interleaved logs from all recognizers and you can only register one event handler as callback function to receive interleaved logs from all recognizers. You cannot get a separate memory logger for each recognizer and you cannot register an event handler for each recognizer. However, `File logger, memory logger and event logger` can coexist in the same process or in the same recognizer.

‎articles/ai-services/speech-service/includes/how-to/diagnostics/java.md

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
author: charles-fu
3+
ms.service: azure-ai-speech
4+
ms.topic: include
5+
ms.date: 03/18/2025
6+
ms.author: changfu001
7+
ms.custom: devx-track-java
8+
---
9+
10+
[!INCLUDE [Introduction](intro.md)]
11+
12+
### Samples
13+
14+
```java
15+
import com.microsoft.cognitiveservices.speech.*;
16+
import com.microsoft.cognitiveservices.speech.diagnostics.logging.EventLogger;
17+
import com.microsoft.cognitiveservices.speech.diagnostics.logging.FileLogger;
18+
import com.microsoft.cognitiveservices.speech.diagnostics.logging.MemoryLogger;
19+
20+
public class SpeechLoggingSamples {
21+
public static void fileLoggerWithoutFilters()
22+
{
23+
FileLogger.start("LogfilePathAndName");
24+
25+
// Other Speech SDK calls
26+
27+
FileLogger.stop();
28+
}
29+
30+
public static void FileLoggerWithFilters()
31+
{
32+
String[] filters = { "YourFirstString", "YourSecondString" };
33+
FileLogger.setFilters(filters);
34+
FileLogger.start("LogfilePathAndName");
35+
36+
// Other Speech SDK calls
37+
38+
FileLogger.stop();
39+
FileLogger.setFilters();
40+
}
41+
42+
public static void memoryLoggerWithoutFilters()
43+
{
44+
MemoryLogger.start();
45+
46+
// Other Speech SDK calls
47+
48+
// At any time (whether logging is stopped) you can dump the traces in memory to a file
49+
MemoryLogger.dump("LogfilePathAndName");
50+
51+
// Or dump to any object that is derived from java.io.Writer. For example, System.out
52+
MemoryLogger.dump(System.out);
53+
54+
// Or dump to a list of strings
55+
List<String> messages = MemoryLogger.dump();
56+
57+
MemoryLogger.stop();
58+
}
59+
60+
public static void eventLoggerWithoutFilters()
61+
{
62+
final Object lockObject = new Object();
63+
List<String> messages = new ArrayList<>();
64+
65+
// Register a callback that will get invoked by Speech SDK on every new log message
66+
EventLogger.setCallback((message) -> {
67+
// Store the message for later processing. Better not processing it in the event thread
68+
synchronized (lockObject) {
69+
messages.add(message);
70+
}
71+
});
72+
73+
// Other Speech SDK calls
74+
75+
// Stop logging by setting an empty callback
76+
EventLogger.setCallback();
77+
}
78+
}
79+
```

‎articles/ai-services/speech-service/includes/how-to/diagnostics/objectivec.md

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
author: charles-fu
3+
ms.service: azure-ai-speech
4+
ms.topic: include
5+
ms.date: 03/18/2025
6+
ms.author: changfu001
7+
ms.custom: devx-track-csharp
8+
---
9+
10+
[!INCLUDE [Introduction](intro.md)]
11+
12+
### Samples
13+
14+
```Objective-C
15+
16+
- (void)fileLoggerWithoutFilters {
17+
NSString *logFileName = @"speech_sdk.log";
18+
NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
19+
stringByAppendingPathComponent:logFileName];
20+
[SPXFileLogger start:logFile];
21+
22+
// Other Speech SDK calls
23+
24+
[SPXFileLogger stop];
25+
}
26+
27+
- (void)fileLoggerWithFilters {
28+
NSString *logFileName = @"speech_sdk.log";
29+
NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
30+
stringByAppendingPathComponent:logFileName];
31+
NSArray *filters = @[@"YourFirstString", @"YourSecondString"];
32+
[SPXFileLogger setFilters:filters];
33+
[SPXFileLogger start:logFile];
34+
35+
// Other Speech SDK calls
36+
37+
[SPXFileLogger stop];
38+
[SPXFileLogger setFilters:nil];
39+
}
40+
41+
- (void)memoryLoggerWithoutFilters {
42+
NSString *logFileName = @"speech_sdk.log";
43+
NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
44+
stringByAppendingPathComponent:logFileName];
45+
46+
[SPXMemoryLogger start];
47+
48+
// Other Speech SDK calls
49+
50+
// At any time (whether logging is stopped) you can dump the traces in memory to a file
51+
[SPXMemoryLogger dumpToFile:logFile];
52+
53+
[SPXMemoryLogger stop];
54+
}
55+
56+
- (void)eventLoggingWithoutFilters {
57+
__block NSMutableArray *eventMsgs = [NSMutableArray array];
58+
59+
// Register a callback that will get invoked by Speech SDK on every new log message
60+
[SPXEventLogger setCallback:^(NSString *message) {
61+
@synchronized(self) {
62+
[eventMsgs addObject:message];
63+
}
64+
}];
65+
66+
// Other Speech SDK calls
67+
68+
// Stop event logging
69+
[SPXEventLogger setCallback:nil];
70+
}
71+
```

0 commit comments

Comments
 (0)