Включение ведения журнала в пакете SDK для распознавания речи

Логирование в файл является необязательной функцией для Speech SDK. На стадии разработки ведение журнала предоставляет дополнительные сведения и средства диагностики основных компонентов SDK для распознавания речи. Логирование осуществляется статическими классами в родной библиотеке Speech SDK. Все экземпляры программ в одном процессе записывают лог-записи в один и тот же файл журнала.

Использование API ведения журнала

Рекомендуемый способ включения ведения журнала — использовать классы статического средства ведения журнала, доступные в пакете SDK службы "Речь" версии 1.43.0 и более поздних версий. API ведения журнала предоставляет три типа средств ведения журнала:

• Средство ведения журнала: записывает сообщения журнала непосредственно в файл. Это самое простое решение для ведения журнала и подходит для диагностики большинства проблем на устройстве.
• Средство ведения журнала памяти: хранит сообщения журнала в фиксированном буфере кольца размером 2 МБ в памяти. Содержимое буфера можно дампать в файл или поток в любое время. Это подходит для диагностики проблем, возникающих в течение короткого периода времени.
• Средство ведения журнала событий: отправляет сообщения журнала в предоставленный обработчик событий. Это подходит, если необходимо интегрировать лог-файлы платформы SDK для распознавания речи с существующей системой сбора лог-файлов.

Эти логгеры — это конструкции для всего процесса. Если у вас несколько объектов распознавателя речи, работающих параллельно, существует один общий журнал, содержащий чередуемые строки журналов со всех распознавателей. Вы можете использовать средство ведения журнала файлов, средство ведения журнала памяти и средство ведения журнала событий одновременно в одном процессе.

using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Diagnostics.Logging;

class Program 
{
    public static void FileLoggerWithoutFilters()
    {
        FileLogger.Start("LogfilePathAndName");

        // Other Speech SDK calls

        FileLogger.Stop();
    }

    public static void FileLoggerWithFilters()
    {
        string[] filters = { "YourFirstString", "YourSecondString" };
        FileLogger.SetFilters(filters);
        FileLogger.Start("LogfilePathAndName");

        // Other Speech SDK calls
        
        FileLogger.Stop();
        FileLogger.SetFilters();
    }

    public static void MemoryLoggerWithoutFilters()
    {
        MemoryLogger.Start();

        // Other Speech SDK calls

        // At any time (whether logging is stopped) you can dump the traces in memory to a file
        MemoryLogger.Dump("LogfilePathAndName");

        // Or dump to any object that is derived from System.IO.TextWriter. For example, System.Console.Out
        MemoryLogger.Dump(System.Console.Out);

        // Or dump to a vector of strings
        List<string> messages = MemoryLogger.Dump().ToList<string>();

        MemoryLogger.Stop();
    }

    // These variables and method are used by the EvenLogger sample below.
    private static readonly object lockObject = new object();
    private static List<string> eventMessages = new List<string>();
    private static void OnMessageEvent(object sender, string message)
    {
        lock (lockObject)
        {
            // Store the message for later processing. Better not processing it in the event thread
            eventMessages.Add(message);
        }
    }

    public static void EventLoggerWithoutFilters()
    {
        // Subscribe an event that will get invoked by Speech SDK on every new log message
        EventLogger.OnMessage += OnMessageEvent;

        // Other Speech SDK calls

        // Unsubscribe to stop getting events
        EventLogger.OnMessage -= OnMessageEvent;
    }
}

using namespace Microsoft::CognitiveServices::Speech;
using namespace Microsoft::CognitiveServices::Speech::Diagnostics::Logging;

void FileLoggerWithoutFilters()
{
    FileLogger::Start("LogfilePathAndName");

    // Other Speech SDK calls

    FileLogger::Stop();
}

void FileLoggerWithFilters()
{
    std::initializer_list<std::string> filters = { "YourFirstString", "YourSecondString" };
    FileLogger::SetFilters(filters);
    FileLogger::Start("LogfilePathAndName");

    // Other Speech SDK calls
    
    FileLogger::Stop();
    FileLogger::SetFilters();
}

void MemoryLoggerWithoutFilters()
{
    MemoryLogger::Start();

    // Other Speech SDK calls

    // At any time (whether logging is stopped) you can dump the traces in memory to a file
    MemoryLogger::Dump("LogfilePathAndName");

    // Or dump to any stream object that is derived from std::ostream. For example, std::cout
    MemoryLogger::Dump(std::cout);

    // Or dump to a vector of strings
    std::vector<std::string> messages = MemoryLogger::Dump();

    MemoryLogger::Stop();
}

void EventLoggerWithoutFilters()
{
    std::mutex mtx;
    std::vector<std::string> messages;

    // Register a callback that will get invoked by Speech SDK on every new log message
    EventLogger::SetCallback([&messages, &mtx](std::string message) {
        // Store the message for later processing. Better not processing it in the event thread
        std::unique_lock<std::mutex> lock(mtx);
        messages.push_back(message);
    });

    // Other Speech SDK calls

    // Stop logging by setting an empty callback
    EventLogger::SetCallback();
}

import com.microsoft.cognitiveservices.speech.*;
import com.microsoft.cognitiveservices.speech.diagnostics.logging.EventLogger;
import com.microsoft.cognitiveservices.speech.diagnostics.logging.FileLogger;
import com.microsoft.cognitiveservices.speech.diagnostics.logging.MemoryLogger;

public class SpeechLoggingSamples {
    public static void fileLoggerWithoutFilters()
    {
        FileLogger.start("LogfilePathAndName");

        // Other Speech SDK calls

        FileLogger.stop();
    }

    public static void FileLoggerWithFilters()
    {
        String[] filters = { "YourFirstString", "YourSecondString" };
        FileLogger.setFilters(filters);
        FileLogger.start("LogfilePathAndName");

        // Other Speech SDK calls
        
        FileLogger.stop();
        FileLogger.setFilters();
    }

    public static void memoryLoggerWithoutFilters()
    {
        MemoryLogger.start();

        // Other Speech SDK calls

        // At any time (whether logging is stopped) you can dump the traces in memory to a file
        MemoryLogger.dump("LogfilePathAndName");

        // Or dump to any object that is derived from java.io.Writer. For example, System.out
        MemoryLogger.dump(System.out);

        // Or dump to a list of strings
        List<String> messages = MemoryLogger.dump();

        MemoryLogger.stop();
    }

    public static void eventLoggerWithoutFilters()
    {
        final Object lockObject = new Object();
        List<String> messages = new ArrayList<>();

        // Register a callback that will get invoked by Speech SDK on every new log message
        EventLogger.setCallback((message) -> {
            // Store the message for later processing. Better not processing it in the event thread
            synchronized (lockObject) {
                messages.add(message);
            }
        });

        // Other Speech SDK calls

        // Stop logging by setting an empty callback
        EventLogger.setCallback();
    }
}

- (void)fileLoggerWithoutFilters {
    NSString *logFileName = @"speech_sdk.log";
    NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
                         stringByAppendingPathComponent:logFileName];
    [SPXFileLogger start:logFile];
    
    // Other Speech SDK calls

    [SPXFileLogger stop];
}

- (void)fileLoggerWithFilters {
    NSString *logFileName = @"speech_sdk.log";
    NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
                         stringByAppendingPathComponent:logFileName];
    NSArray *filters = @[@"YourFirstString", @"YourSecondString"];
    [SPXFileLogger setFilters:filters];
    [SPXFileLogger start:logFile];
    
    // Other Speech SDK calls

    [SPXFileLogger stop];
    [SPXFileLogger setFilters:nil];
}

- (void)memoryLoggerWithoutFilters {
    NSString *logFileName = @"speech_sdk.log";
    NSString *logFile = [[NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
                         stringByAppendingPathComponent:logFileName];

    [SPXMemoryLogger start];
    
    // Other Speech SDK calls

    // At any time (whether logging is stopped) you can dump the traces in memory to a file
    [SPXMemoryLogger dumpToFile:logFile];

    [SPXMemoryLogger stop];
}

- (void)eventLoggingWithoutFilters {
    __block NSMutableArray *eventMsgs = [NSMutableArray array];

    // Register a callback that will get invoked by Speech SDK on every new log message
    [SPXEventLogger setCallback:^(NSString *message) {
        @synchronized(self) {
            [eventMsgs addObject:message];
        }
    }];
    
    // Other Speech SDK calls

    // Stop event logging 
    [SPXEventLogger setCallback:nil];
}

import azure.cognitiveservices.speech as speechsdk
import azure.cognitiveservices.speech.diagnostics.logging as speechsdk_logging


def file_logger_without_filters():
    speechsdk_logging.FileLogger.start("LogfilePathAndName")
    # Other Speech SDK calls
    speechsdk_logging.FileLogger.stop()


def file_logger_with_filters():
    filters = { "YourFirstString", "YourSecondString" }
    speechsdk_logging.FileLogger.set_filters(filters)
    speechsdk_logging.FileLogger.start("LogfilePathAndName")
    # Other Speech SDK calls
    speechsdk_logging.FileLogger.stop()
    speechsdk_logging.FileLogger.set_filters()


def memory_logger_without_filter():
    speechsdk_logging.MemoryLogger.start()
    #
    # Other Speech SDK calls
    #
    # At any time (whether logging is stopped) you can dump the traces in memory to a file
    speechsdk_logging.MemoryLogger.dump("LogfilePathAndName")
    # Or dump to any object that is derived from IOBase. For example, sys.stdout
    speechsdk_logging.MemoryLogger.dump_to_stream(sys.stdout)
    # Or dump to a list of strings
    messages = speechsdk_logging.MemoryLogger.dump_to_list()
    speechsdk_logging.MemoryLogger.stop()


def event_logger_without_filter():
    messages = []
    lock = threading.Lock()
    # Register a callback that will get invoked by Speech SDK on every new log message
    def on_log(msg):
        with lock:
            # Store the message for later processing. Better not processing it in the event thread
            messages.append(msg)
    speechsdk_logging.EventLogger.set_callback(on_log)
    #
    # Other Speech SDK calls
    #
    # Stop logging by setting an empty callback
    speechsdk_logging.EventLogger.set_callback()

JavaScript

Для JavaScript ведение журнала включено с помощью диагностики пакета SDK:

sdk.Diagnostics.SetLoggingLevel(sdk.LogLevel.Debug);
sdk.Diagnostics.SetLogOutputPath("LogfilePathAndName");

Расположения файлов журнала по платформе

При использовании FileLogger.Start() или MemoryLogger.Dump()укажите путь к файлу. Требования к пути зависят от платформы.

Для Windows или Linux файл журнала может находиться в любом пути, для которого у пользователя есть разрешение на запись. Разрешения на запись в местоположениях файловой системы в других операционных системах могут быть по умолчанию ограничены или запрещены.

Универсальная платформа Windows (UWP)

Приложения UWP должны размещать файлы журналов в одном из расположений данных приложения (локальное, перемещаемое или временное). Файл журнала можно создать в локальной папке приложения.

StorageFolder storageFolder = ApplicationData.Current.LocalFolder;
StorageFile logFile = await storageFolder.CreateFileAsync("logfile.txt", CreationCollisionOption.ReplaceExisting);
FileLogger.Start(logFile.Path);

В приложении UWP для Unity файл журнала можно создать с помощью папки с постоянными путями к данным приложения следующим образом:

#if ENABLE_WINMD_SUPPORT
    string logFile = Application.persistentDataPath + "/logFile.txt";
    FileLogger.Start(logFile);
#endif

Дополнительные сведения о разрешениях на доступ к файлам в приложениях UWP см. в разделе Разрешения на доступ к файлам.

Android

Файл журнала можно сохранить во внутреннем хранилище, во внешнем хранилище или в каталоге кэша. Файлы, созданные во внутреннем хранилище или в каталоге кэша, являются частными для приложения. Рекомендуется создать файл журнала во внешнем хранилище.

File dir = context.getExternalFilesDir(null);
File logFile = new File(dir, "logfile.txt");
FileLogger.start(logFile.getAbsolutePath());

Код сохраняет файл журнала во внешнем хранилище в корневом каталоге конкретного приложения. Пользователь может получить доступ к файлу с помощью диспетчера файлов (обычно в Android/data/ApplicationName/logfile.txt). Файл удаляется при удалении приложения.

Кроме того, необходимо запросить разрешение WRITE_EXTERNAL_STORAGE в файле манифеста.

<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="...">
  ...
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  ...
</manifest>

В приложении Unity для Android файл журнала можно создать, используя папку постоянного пути к данным приложения следующим образом:

string logFile = Application.persistentDataPath + "/logFile.txt";
FileLogger.Start(logFile);

Кроме того, необходимо задать разрешение на запись в параметрах проигрывателя Unity для Android значение External (SDCard)". Журнал записывается в каталог, который можно получить с помощью инструмента, например AndroidStudio Device File Explorer. Точный путь к каталогу может отличаться между устройствами Android. Расположение обычно - это папка sdcard/Android/data/your-app-packagename/files.

Дополнительные сведения о хранилище данных и файлах для приложений Android см. в обзоре хранилища данных и файлов.

iOS

Доступны только каталоги в изолированной среде приложения. Файлы можно создавать в каталогах Documents, Library и TEMP. Файлы в каталоге документов можно сделать доступными для пользователя.

Если вы используете Objective-C в iOS, используйте следующий фрагмент кода, чтобы создать файл журнала в каталоге документов приложения:

NSString *filePath = [
  [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject]
    stringByAppendingPathComponent:@"logfile.txt"];
[SPXFileLogger start:filePath];

Чтобы получить доступ к созданному файлу, добавьте следующие свойства в Info.plist список свойств приложения:

<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>

Если вы используете Swift в iOS, используйте следующий фрагмент кода, чтобы включить журналы:

let documentsDirectoryPathString = NSSearchPathForDirectoriesInDomains(.documentDirectory, .userDomainMask, true).first!
let documentsDirectoryPath = NSURL(string: documentsDirectoryPathString)!
let logFilePath = documentsDirectoryPath.appendingPathComponent("swift.log")
SPXFileLogger.start(logFilePath!.absoluteString)

Дополнительные сведения о файловой системе iOS см. в руководстве по программированию файловой системы.

Устаревший подход: установка свойства для объекта конфигурации

Вы также можете включить ведение журнала, задав Speech_LogFilename свойство для объекта конфигурации речи. Этот подход менее гибкий, чем использование статических классов логгеров.

Взяв SpeechConfig в качестве примера и предполагая, что вы создали экземпляр под названием speechConfig:

speechConfig.SetProperty(PropertyId.Speech_LogFilename, "LogfilePathAndName");

speechConfig.setProperty(PropertyId.Speech_LogFilename, "LogfilePathAndName");

speechConfig->SetProperty(PropertyId::Speech_LogFilename, "LogfilePathAndName");

speech_config.set_property(speechsdk.PropertyId.Speech_LogFilename, "LogfilePathAndName")

[speechConfig setPropertyTo:@"LogfilePathAndName" byId:SPXSpeechLogFilename];

import ("github.com/Microsoft/cognitive-services-speech-sdk-go/common")

speechConfig.SetProperty(common.SpeechLogFilename, "LogfilePathAndName")

Вы можете создать распознаватель из объекта конфигурации. Это позволяет ведение журнала для всех распознавателей.

Чтобы получить рекомендации по пути к файлам для конкретной платформы, см. раздел "Местоположения файлов журналов по платформам". Те же требования к пути применяются при использовании подхода с использованием свойств.

Логирование с несколькими распознавателями

При использовании устаревшего метода работы с свойствами выходной путь файла журнала указывается как свойство конфигурации в объекте SDK SpeechRecognizer или другом объекте SDK. Однако ведение журнала ПАКЕТА SDK — это однопроцессное средство без концепции отдельных экземпляров. Его можно представить в виде конструктора SpeechRecognizer (или его аналога), неявно вызывающего статическую внутреннюю подпрограмму "Configure Global Logging" с данными свойств, доступными в соответствующем классе SpeechConfig.

Это означает, что невозможно настроить шесть параллельных распознавателей для одновременного вывода на шесть отдельных файлов. Вместо этого последний созданный распознаватель настроит глобальный экземпляр ведения журнала для вывода в файл, указанный в свойствах его конфигурации, и все журналы SDK выводятся в этот файл.

Это также означает, что время существования объекта, настроенного ведения журнала, не привязано к длительности ведения журнала. Ведение журнала не остановится в ответ на выпуск объекта ПАКЕТА SDK и будет продолжаться до тех пор, пока новая конфигурация ведения журнала не будет предоставлена. После запуска ведение журнала на уровне процесса можно остановить, задав путь к файлу журнала пустой строке при создании нового объекта.

Чтобы уменьшить потенциальную путаницу при настройке ведения журнала для нескольких экземпляров, может быть полезно абстрагировать управление ведением журнала из объектов, выполняющих реальную работу. Вот пример пары вспомогательных подпрограмм.

void EnableSpeechSdkLogging(const char* relativePath)
{
	auto configForLogging = SpeechConfig::FromSubscription("unused_key", "unused_region");
	configForLogging->SetProperty(PropertyId::Speech_LogFilename, relativePath);
	auto emptyAudioConfig = AudioConfig::FromStreamInput(AudioInputStream::CreatePushStream());
	auto temporaryRecognizer = SpeechRecognizer::FromConfig(configForLogging, emptyAudioConfig);
}

void DisableSpeechSdkLogging()
{
	EnableSpeechSdkLogging("");
}

Следующие шаги