Logging es ES

Registro

ASF te permite configurar tu propio módulo de registro personalizado que se utilizará durante el tiempo de ejecución. Lo puedes hacer poniendo un archivo especial llamado NLog.config en el directorio de la aplicación. Puedes leer toda la documentación de NLog en NLog wiki, pero además aquí también encontrarás algunos ejemplos útiles.

Registro por defecto

Usar una configuración de NLog personalizada automáticamente desactiva la predeterminada de ASF, que incluye ColoredConsole y File. En otras palabras, tu configuración anula por completo el registro predeterminado de ASF, lo que significa que si quieres mantener el objetivo ColoredConsole, debes definirlo tú mismo. Esto te permite no solo añadir objetivos de registro adicionales, sino también desactivar o modificar los predeterminados.

Si quieres usar el registro por defecto de ASF sin modificaciones, no necesitas hacer nada - tampoco necesitas definirlo en NLog.config. No uses el NLog.config personalizado si no quieres modificar el registro predeterminado de ASF. Para referencia, el equivalente del registro predeterminado de ASF sería:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" layout="${date:format=yyyy-MM-dd HH\:mm\:ss}|${processname}-${processid}|${level:uppercase=true}|${logger}|${message}${onexception:inner= ${exception:format=toString,Data}}" />
    <target xsi:type="File" name="File" deleteOldFileOnStartup="true" fileName="log.txt" layout="${date:format=yyyy-MM-dd HH\:mm\:ss}|${processname}-${processid}|${level:uppercase=true}|${logger}|${message}${onexception:inner= ${exception:format=toString,Data}}" />
    <!-- Below becomes active when ASF's IPC interface is started -->
    <!-- <target type="History" name="History" layout="${date:format=yyyy-MM-dd HH\:mm\:ss}|${processname}-${processid}|${level:uppercase=true}|${logger}|${message}${onexception:inner= ${exception:format=toString,Data}}" maxCount="20" /> -->
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
    <logger name="*" minlevel="Debug" writeTo="File" />
    <!-- Below becomes active when ASF's IPC interface is started -->
    <!-- <logger name="*" minlevel="Debug" writeTo="History" /> -->
  </rules>
</nlog>

Integración de ASF

ASF incluye algunos trucos de código que mejoran su integración NLog, permitiéndote captar mensaje específicos con más facilidad.

La variable ${logger} específica de NLog siempre distinguirá el origen del mensaje - será BotName de uno de tus bots, o ASF si el mensaje viene directamente del proceso ASF. Así puedes captar mensajes fácilmente considerando bots específicos, o el proceso ASF (solo), en lugar de todos ellos, basado en el nombre del logger.

ASF intenta marcar los mensaje de forma adecuada basándose en los niveles de advertencia proporcionados por NLog, lo que hace posible captar solo mensajes específicos de niveles de registro específicos en lugar de todos ellos. Por supuesto, el nivel de registro para un mensaje específico no puede ser personalizado, ya que es decisión de ASF qué tan serio es un mensaje, pero definitivamente puedes hacer a ASF menos/más silencioso, como te parezca oportuno.

ASF registra información adicional, tal como usuario/mensajes de chat en el nivel de registro Trace. El registro por defecto de ASF solo registra el nivel Debug y superior, el cual oculta esa información adicional, ya que no es necesaria para la mayoría de los usuarios, además de que se opacan mensajes potencialmente más importantes. Sin embargo puedes usar esa información reactivando el nivel de registro Trace, especialmente en combinación con registrar solo un bot específico de tu elección, con el evento particular en el que estás interesado.

En general, ASF intenta hacerlo tan fácil y conveniente como sea posible, registrar solo los mensajes que quieres en lugar de obligarte a filtrarlos manualmente mediante herramientas de terceros como grep y similares. Simplemente configura NLog correctamente como se escribe a configure, y deberías poder especificar incluso reglas muy complejas de registro con objetivos personalizados tal como bases de datos enteras.

En cuanto a la versión - ASF siempre intenta salir con la versión más actualizada de NLog que esté disponible en NuGet al momento de la publicación de ASF. A menudo es una versión más reciente que la última estable, por lo tanto no debería haber problema por usar en ASF cualquier función que puedas encontrar en la wiki de NLog, incluso funciones que están en desarrollo y estado WIP (work in process). solo asegúrate de que también estás usando ASF actualizado.

Como parte de la integración, ASF también incluye soporte para objetivos de registro adicionales de ASF NLog, lo que se explica abajo.

Ejemplos

Empecemos con algo sencillo. Solo usaremos el objetivo ColoredConsole. Nuestro NLog.config inicial se verá así:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
  </rules>
</nlog>

La explicación de la configuración de arriba es bastante sencilla - definimos un objetivo de registro, que es ColoredConsole, luego redirigimos todos los loggers (*) de nivel Debug o superior al objetivo ColoredConsole que definimos previamente. Eso es todo.

Si inicias ASF con el NLog.config de arriba, solo el objetivo ColoredConsole estará activo, y ASF no escribirá a File, independientemente de la configuración de NLog codificada dentro de ASF.

Ahora digamos que no nos gusta el formato de ${longdate}|${level:uppercase=true}|${logger}|${message} y solo queremos registrar el mensaje. Lo podemos hacer modificando el Layout de nuestro objetivo.

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" layout="${message}" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
  </rules>
</nlog>

Si inicias ASF ahora, notarás que desapareció la fecha, el nivel y nombre del logger - dejando solo mensajes de ASF en formato Function() Message.

También podemos modificar la configuración para registrar a más de un objetivo. Vamos a registrar en ColoredConsole y File al mismo tiempo.

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" />
    <target xsi:type="File" name="File" fileName="NLog.txt" deleteOldFileOnStartup="true" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
    <logger name="*" minlevel="Debug" writeTo="File" />
  </rules>
</nlog>

Y listo, ahora registraremos todo a ColoredConsole y File. ¿Notaste que también puedes especificar un fileName personalizado y opciones adicionales?

Por último, ASF usa varios niveles de registro, para facilitar que entiendas lo que está sucediendo. Podemos usar esa información para modificar la severidad del registro. Digamos que queremos registrar todo (Trace) a File, pero solo el nivel de registro Warning y superior a ColoredConsole. Podemos lograrlo modificando nuestras rules reglas:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" />
    <target xsi:type="File" name="File" fileName="NLog.txt" deleteOldFileOnStartup="true" />
  </targets>

  <rules>
    <logger name="*" minlevel="Warn" writeTo="ColoredConsole" />
    <logger name="*" minlevel="Trace" writeTo="File" />
  </rules>
</nlog>

Eso es todo, ahora nuestra ColoredConsole solo mostrará advertencias y superior, mientras que todavía registra todo a File. Puedes modificarlo aún más para registrar, por ejemplo solo Info e inferior, y así por el estilo.

Finalmente, hagamos algo un poco más avanzado y vamos a registrar todos los mensajes al archivo, pero solo del bot llamado LogBot.

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" />
    <target xsi:type="File" name="LogBotFile" fileName="LogBot.txt" deleteOldFileOnStartup="true" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
    <logger name="LogBot" minlevel="Trace" writeTo="LogBotFile" />
  </rules>
</nlog>

Puedes ver cómo usamos la integración ASF y fácilmente distinguimos la fuente del mensaje basados en la propiedad ${logger}.

Uso avanzado

Los ejemplos anteriores son bastante sencillos y hechos para mostrarte lo fácil que es definir tus propias reglas de registro que se pueden usar con ASF. Puedes usar NLog para diferentes cosas, incluyendo objetivos complejos (tal como mantener los registros en Database), rotación de registros (tal como eliminar registros File viejos), usar Layout personalizados, declarar tu propio filtro de registro <when> y mucho más. Te invito a leer toda la documentación NLog para aprender sobre todas las opciones que tienes disponibles, permitiéndote modificar el módulo de registro de ASF de la forma que quieras. Es una herramienta muy potente y personalizar el registro de ASF nunca fue tan fácil.

Limitaciones

ASF desactivará temporalmente todas las reglas que incluyan los objetivos ColoredConsole o Console cuando espere interacción del usuario. Por lo tanto, si quieres seguir registrando para otros objetivos incluso cuando ASF espera interacción del usuario, debes definir esos objetivos con sus propias reglas, como se mostró en los ejemplos anteriores, en lugar de poner muchos objetivos en writeTo de la misma regla (a menos que este sea el comportamiento deseado). La desactivación temporal de los objetivos de la consola se hace para mantenerla limpia cuando se está esperando interacción del usuario.

Registro de chat

ASF incluye soporte extendido para registro de chat no solo grabando todos los mensajes recibidos/enviados en el nivel de registro Trace, sino también exponiendo información adicional relacionada con ellos en propiedades de evento. Esto es porque de todos modos necesitamos manejar los mensajes de chat como comandos, así que no nos cuesta nada registrar esos eventos para hacer posible que añadas lógica adicional (tal como hacer ASF tu archivo personal de conversaciones de Steam).

Propiedades de evento

Nombre	Descripción
Echo	Tipo `bool`. Se establece a `true` cuando el mensaje se envía desde nosotros al destinatario, y `false` de lo contrario.
Message	Tipo `string`. Este es el mensaje enviado/recibido.
ChatGroupID	Tipo `ulong`. Este es el ID del chat de grupo para mensajes enviados/recibidos. Será `0` cuando no se utilice ningún chat para transmitir este mensaje.
ChatID	Tipo `ulong`. Este es el ID del canal `ChatGroupID` para mensajes enviados/recibidos. Será `0` cuando no se utilice ningún chat para transmitir este mensaje.
SteamID	Tipo `ulong`. Este es el ID del usuario de Steam para mensajes enviados/recibidos. Puede ser `0` cuando ningún usuario en particular está involucrado en la transmisión del mensaje (por ejemplo, cuando somos nosotros enviando un mensaje a un chat de grupo).

Ejemplo

Este ejemplo se basa en nuestro ejemplo básico de ColoredConsole que se mostró antes. Antes de intentar entenderlo, te recomiendo echar un vistazo arriba para aprender primero los fundamentos del registro NLog.

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target xsi:type="ColoredConsole" name="ColoredConsole" />
    <target xsi:type="File" name="ChatLogFile" fileName="${event-properties:item=ChatGroupID}-${event-properties:item=ChatID}${when:when='${event-properties:item=ChatGroupID}' == 0:inner=-${event-properties:item=SteamID}}.txt" layout="${date:format=yyyy-MM-dd HH\:mm\:ss} ${event-properties:item=Message} ${when:when='${event-properties:item=Echo}' == 'true':inner=-&gt;:else=&lt;-} ${event-properties:item=SteamID}" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="ColoredConsole" />
    <logger name="MainAccount" level="Trace" writeTo="ChatLogFile">
      <filters>
        <when condition="not starts-with('${message}','OnIncoming') and not starts-with('${message}','SendMessage')" action="Ignore" />
      </filters>
    </logger>
  </rules>
</nlog>

Hemos empezado desde nuestro ejemplo básico de ColoredConsole y lo hemos extendido. En primer lugar, hemos preparado un archivo permanente de registro de char por cada grupo y usuario de Steam - esto es posible gracias a las propiedades adicionales que ASF nos expone de manera elegante. También hemos decidido ir con un layout personalizado que solo escribe la fecha actual, el mensaje, información enviada/recibida y el usuario de Steam. Por último, hemos habilitado nuestra regla de registro de chat para el nivel Trace, solo para nuestro bot MainAccount y solo para funciones relacionadas con el registro de chat (OnIncoming* que es usado para recibir mensajes y ecos, y SendMessage* para enviar mensajes de ASF).

El ejemplo anterior generará el archivo 0-0-76561198069026042.txt cuando se hable con ArchiBoT:

2018-07-26 01:38:38 ¿cómo te va? -> 76561198069026042
2018-07-26 01:38:38 me va genial, ¿qué hay de ti? <- 76561198069026042

Claro que este solo es un ejemplo funcional con algunos trucos de layout mostrados de forma práctica. Puedes ampliar esta idea a tus propias necesidades, tal como filtrado extra, orden personalizado, un layout personal, grabar solo mensajes recibidos, etcétera.

Objetivos de ASF

Además de los objetivos estándar de registro de NLog (tal como ColoredConsole y File explicados arriba), también puedes usar objetivos de registro de ASF personalizados.

Para máxima integridad, la definición de los objetivos de ASF seguirá la convención de la documentación de NLog.

SteamTarget

Como puedes adivinar, este objetivo utiliza mensajes de chat de Steam para registrar mensajes de ASF. Puedes configurarlo para usar un chat de grupo, o un chat privado. Además de especificar un objetivo de Steam para tus mensajes, también puedes especificar el botName nombre del bot que debe enviarlos.

Soportado en todos los entornos utilizados por ASF.

Sintaxis de configuración

<targets>
  <target type="Steam"
          name="String"
          layout="Layout"
          chatGroupID="Ulong"
          steamID="Ulong"
          botName="String" />
</targets>

Lee más sobre el uso del Archivo de Configuración.

Parámetros

Opciones Generales

name - Nombre del objetivo.

Opciones de Layout

layout - Texto a ser renderizado. Layout Requerido. Por defecto: ${level:uppercase=true}|${logger}|${message}

Opciones de SteamTarget

chatGroupID - ID del chat de grupo declarado como entero largo sin firmar de 64 bits. No requerido. Por defecto en 0 lo que deshabilitará la funcionalidad de chat grupo y en su lugar usará el chat privado. Cuando está habilitado (establecido en valor diferente a cero), la propiedad steamID actúa como chatID y especifica el ID del canal en este chatGroupID al que el bot debe enviar mensajes.

steamID - SteamID declarado como entero largo sin firmar de 64 bits del usuario de Steam objetivo (como SteamOwnerID), u objetivo chatID (cuando chatGroupID está establecido). Requerido. Por defecto en 0 lo que deshabilita completamente el objetivo de registro.

botName - Nombre del bot (como es reconocido por ASF, sensible a mayúsculas) del bot objetivo que enviará mensajes al steamID declarado arriba. No requerido. Por defecto en null lo que seleccionará automáticamente cualquier bot conectado actualmente. Se recomienda establecer este valor adecuadamente, ya que SteamTarget no toma en cuenta muchas limitaciones de Steam, como el hecho de que debes tener el steamID del objetivo en tu lista de amigos.

Ejemplos de SteamTarget

Para escribir todos los mensajes del nivel Debug y superior, desde el bot llamado MyBot a steamID de 76561198006963719, debes usar un NLog.config similar al siguiente:

<?xml version="1.0" encoding="utf-8" ?>
<nlog xmlns="http://www.nlog-project.org/schemas/NLog.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <targets>
    <target type="Steam" name="Steam" steamID="76561198006963719" botName="MyBot" />
  </targets>

  <rules>
    <logger name="*" minlevel="Debug" writeTo="Steam" />
  </rules>
</nlog>

Aviso: Nuestro SteamTarget es un objetivo personalizado, así que debes asegurarte de que lo declaras como type="Steam", NO xsi:type="Steam", ya que xsi está reservado objetivos oficiales soportados por NLog.

Cuando ejecutes ASF con un NLog.config similar al anterior, MyBot comenzará a enviar mensajes al usuario de Steam 76561198006963719 con todos los mensajes de registro habituales de ASF. Ten en cuenta que MyBot debe estar conectado para enviar mensajes, por lo que todos los mensajes de ASF iniciales que ocurrieron antes de que nuestro bot pudiera conectarse a la red de Steam, no serán reenviados.

Por supuesto, SteamTarget tiene todas las funciones típicas que podrías esperar de TargetWithLayout genérico, así que puedes usarlo junto con, por ejemplo, layouts personalizados, nombres o reglas de registro avanzadas. El ejemplo anterior solo es el más básico.

Capturas de pantalla

Captura de pantalla

HistoryTarget

Este objetivo es usado internamente por ASF para proporcionar un historial de registro de tamaño fijo en /Api/NLog endpoint of ASF API que posteriormente puede ser consumido por ASF-ui y otras herramientas. En general, debes definir este objetivo solo si ya estás usando una configuración personalizada de NLog para otras personalizaciones y también quieres que el registro se exponga en ASF API, por ejemplo, para ASF-ui. También puede ser declarado cuando quieres modificar el layout predeterminado o maxCount la cantidad máxima de mensajes guardados.

Soportado en todos los entornos utilizados por ASF.

Sintaxis de configuración

<targets>
  <target type="History"
          name="String"
          layout="Layout"
          maxCount="Byte" />
</targets>

Lee más sobre el uso del Archivo de Configuración.

Parámetros

Opciones Generales

name - Nombre del objetivo.

Opciones de Layout

layout - Texto a ser renderizado. Layout Requerido. Por defecto: ${date:format=yyyy-MM-dd HH\:mm\:ss}|${processname}-${processid}|${level:uppercase=true}|${logger}|${message}${onexception:inner= ${exception:format=toString,Data}}

Opciones de HistoryTarget

maxCount - Cantidad máxima de registros almacenados para historial bajo demanda. No requerido. Por defecto en 20 lo que es un buen balance para proporcionar el historial inicial, mientras se sigue teniendo en cuenta el uso de memoria que viene de los requisitos de almacenamiento. Debe ser mayor a 0.

Advertencias

Ten cuidado cuando decidas combinar el nivel de registro Debug on inferior en tu SteamTarget con un steamID que tome parte en el proceso de ASF. Esto puede derivar potencialmente en StackOverflowException porque crearás un bucle infinito de ASF recibiendo un mensaje dado, luego registrándolo a través de Steam, resultando en otro mensaje que necesita ser registrado. Actualmente la única posibilidad de que ocurra es registrar el nivel Trace (donde ASF registra sus propios mensajes de chat), o el nivel Debug mientras también se ejecuta ASF en modo Debug (donde ASF registra todos los paquetes de Steam).

En resumen, si tu steamID toma parte en el mismo proceso de ASF, entonces el minlevel nivel mínimo de registro de tu SteamTarget debe ser Info (o Debug si no estás ejecutando ASF en modo Debug) y superior. Alternativamente puedes definir tu propio filtro de registro <when> para evitar un bucle de registro infinito, si modificar el nivel no es apropiado para tu caso. Esta advertencia también aplica para los chats de grupo.