Estruturar microsserviços: Início de sessão e monitorizaçãoDesigning microservices: Logging and monitoring

Em qualquer aplicativo complexo, em algum momento algo dê errado.In any complex application, at some point something will go wrong. Num aplicativo de microsserviços, precisa controlar o que está acontecendo em dezenas ou até mesmo centenas de serviços.In a microservices application, you need to track what's happening across dozens or even hundreds of services. Registo e monitorização são extremamente importantes para lhe dar uma visão holística do sistema.Logging and monitoring are critically important to give you a holistic view of the system.

Diagrama de monitorização numa arquitetura de microsserviços

Numa arquitetura de microsserviços, pode ser especialmente um desafio para identificar a causa exata dos erros ou afunilamentos de desempenho.In a microservices architecture, it can be especially challenging to pinpoint the exact cause of errors or performance bottlenecks. Uma única operação de utilizador poderá abranger vários serviços.A single user operation might span multiple services. Serviços podem atingir os limites de e/s de rede dentro do cluster.Services may hit network I/O limits inside the cluster. Uma cadeia de chamadas em todos os serviços pode provocar backpressure no sistema, resultando em alta latência ou em cascata de falhas.A chain of calls across services may cause backpressure in the system, resulting in high latency or cascading failures. Além disso, geralmente não sabe nó que um determinado contêiner será executado no.Moreover, you generally don't know which node a particular container will run in. Contentores colocados no mesmo nó podem estar competindo pelo limitada da CPU ou memória.Containers placed on the same node may be competing for limited CPU or memory.

Para fazer sentido do que está acontecendo, tem de recolher telemetria da aplicação.To make sense of what's happening, you must collect telemetry from the application. Telemetria pode ser dividida em logs e métricas.Telemetry can be divided into logs and metrics. O Azure Monitor recolhe métricas e registos em toda a plataforma do Azure.Azure Monitor collects both logs and metrics across the Azure platform.

Registos são baseados em texto registos de eventos que ocorrem enquanto a aplicação está em execução.Logs are text-based records of events that occur while the application is running. Eles incluem coisas como registos de aplicações (declarações de rastreio) ou de registos do servidor web.They include things like application logs (trace statements) or web server logs. Os registos são úteis principalmente para analisar a causa forense e de raiz.Logs are primarily useful for forensics and root cause analysis.

Métricas são valores numéricos que podem ser analisados.Metrics are numerical values that can be analyzed. Pode usá-los para observar o sistema em tempo real (ou quase em tempo real) ou para analisar as tendências de desempenho ao longo do tempo.You can use them to observe the system in real time (or close to real time), or to analyze performance trends over time. As métricas mais podem ser subcategorized da seguinte forma:Metrics can be further subcategorized as follows:

  • Ao nível do nó métricas, como CPU, memória, rede, disco e utilização do sistema de ficheiros.Node-level metrics, including CPU, memory, network, disk, and file system usage. As métricas do sistema ajudá-lo a compreender a alocação de recursos para cada nó do cluster e resolver problemas de valores atípicos.System metrics help you to understand resource allocation for each node in the cluster, and troubleshoot outliers.

  • Contentor métricas.Container metrics. Se os serviços são executados dentro de contentores, terá de recolher as métricas ao nível do contentor, não apenas no nível da VM.If services are run inside containers, you need to collect metrics at the container level, not just at the VM level. Pode configurar o Azure Monitor para monitorizar cargas de trabalho do contentor no Azure Kubernetes Service (AKS).You can set up Azure Monitor to monitor container workloads in Azure Kubernetes Service (AKS). Para obter mais informações, consulte Monitor do Azure para contentores-descrição geral.For more information, see Azure Monitor for containers overview. Para outros orquestradores de contentor, utilize o solução de monitorização do contentor de mensagens em fila no Log Analytics.For other container orchestrators, use the Container Monitoring solution in Log Analytics.

  • Aplicação métricas.Application metrics. Isto inclui qualquer métricas que são relevantes para compreender o comportamento de um serviço.This includes any metrics that are relevant to understanding the behavior of a service. Os exemplos incluem o número de pedidos de HTTP de entrada em fila, a latência de pedidos ou o comprimento da fila de mensagens.Examples include the number of queued inbound HTTP requests, request latency, or message queue length. Aplicativos também podem criar métricas personalizadas que são específicas para o domínio, como o número de transações comerciais processados por minuto.Applications can also create custom metrics that are specific to the domain, such as the number of business transactions processed per minute. Uso Application Insights para ativar as métricas de aplicação.Use Application Insights to enable application metrics.

  • Serviço dependente métricas.Dependent service metrics. Os serviços podem chamar serviços externos ou pontos de extremidade, como os serviços PaaS geridos ou serviços SaaS.Services may call external services or endpoints, such as managed PaaS services or SaaS services. Serviços de terceiros podem ou não fornecer todas as métricas.Third-party services may or may not provide any metrics. Caso contrário, terá que se baseiam nas suas próprias métricas de aplicação para controlar as estatísticas de latência e a taxa de erros.If not, you'll have to rely on your own application metrics to track statistics for latency and error rate.

ConsideraçõesConsiderations

O artigo monitorização e diagnóstico descreve as melhores práticas gerais para monitorizar uma aplicação.The article Monitoring and diagnostics describes general best practices for monitoring an application. Aqui estão alguns itens específicos de pensar no contexto de uma arquitetura de microsserviços.Here are some particular things to think about in the context of a microservices architecture.

Configuração e gestão.Configuration and management. Irá utilizar um serviço gerido para o registo e monitorização ou implementar o registo e monitorização de componentes como contentores dentro do cluster?Will you use a managed service for logging and monitoring, or deploy logging and monitoring components as containers inside the cluster? Para obter mais discussões destas opções, consulte a secção opções de tecnologia abaixo.For more discussion of these options, see the section Technology Options below.

Taxa de ingestão.Ingestion rate. O que é o débito em que o sistema pode ingerir eventos de telemetria?What is the throughput at which the system can ingest telemetry events? O que acontece se essa taxa é excedida?What happens if that rate is exceeded? Por exemplo, o sistema pode limitar os clientes, caso em que os dados de telemetria são perdidos ou ele pode downsample os dados.For example, the system may throttle clients, in which case telemetry data is lost, or it may downsample the data. Por vezes, pode minimizar o problema, reduzindo a quantidade de dados que recolhe:Sometimes you can mitigate this problem by reducing the amount of data that you collect:

  • Agregar as métricas, calculando estatísticas, como a média e o desvio-padrão e enviar esses dados de estatísticos para o sistema de monitorização.Aggregate metrics by calculating statistics, such as average and standard deviation, and send that statistical data to the monitoring system.
  • Os dados de Downsample — ou seja, processar apenas uma porcentagem dos eventos.Downsample the data — that is, process only a percentage of the events.
  • Os dados para reduzir o número de chamadas de rede para o serviço de monitoramento do batch.Batch the data to reduce the number of network calls to the monitoring service.

Custo.Cost. O custo de ingestão e armazenamento de dados de telemetria pode ser alto, especialmente em grandes volumes.The cost of ingesting and storing telemetry data may be high, especially at high volumes. Em alguns casos ele ainda poderá exceder o custo de executar a aplicação.In some cases it could even exceed the cost of running the application. Nesse caso, terá de reduzir o volume de telemetria ao agregar, downsampling, ou os dados de criação de batches, conforme descrito acima.In that case, you may need to reduce the volume of telemetry by aggregating, downsampling, or batching the data, as described above.

Fidelidade de dados.Data fidelity. Grau de precisão são as métricas?How accurate are the metrics? Médias podem ocultar valores atípicos, especialmente em escala.Averages can hide outliers, especially at scale. Além disso, se a taxa de amostragem for demasiado baixa, ele pode suavizar flutuações dos dados.Also, if the sampling rate is too low, it can smooth out fluctuations in the data. Pode parecer que todos os pedidos têm sobre a mesma latência de ponto-a-ponto, quando na verdade uma fração significativa de pedidos está a demorar muito mais tempo.It may appear that all requests have about the same end-to-end latency, when in fact a significant fraction of requests are taking much longer.

Latência.Latency. Para ativar a monitorização em tempo real e alertas, os dados telemétricos devem estar disponíveis rapidamente.To enable real-time monitoring and alerts, telemetry data should be available quickly. Como "em tempo real" são os dados apresentados no dashboard de monitorização?How "real-time" is the data that appears on the monitoring dashboard? Alguns segundos antigo?A few seconds old? Mais de um minuto?More than a minute?

Armazenamento.Storage. Para os registos, poderá ser mais eficiente para gravar os eventos de registo armazenamento efémero do cluster e configurar um agente para enviar os ficheiros de registo para o armazenamento mais persistente.For logs, it may be most efficient to write the log events to ephemeral storage in the cluster, and configure an agent to ship the log files to more persistent storage. Dados, eventualmente, devem ser movidos para o armazenamento de longo prazo, para que fique disponível para análise retrospectiva.Data should eventually be moved to long-term storage so that it's available for retrospective analysis. Uma arquitetura de microsserviços pode gerar um grande volume de dados de telemetria, portanto, o custo de armazenar esses dados é uma consideração importante.A microservices architecture can generate a large volume of telemetry data, so the cost of storing that data is an important consideration. Além disso, considere como irá consultar os dados.Also consider how you will query the data.

Dashboard e visualização.Dashboard and visualization. Obtém uma visão holística do sistema, em todos os serviços, tanto dentro do cluster e a serviços externos?Do you get a holistic view of the system, across all of the services, both within the cluster and external services? Se estiver a escrever dados de telemetria e registos para mais de um único local, pode o dashboard de mostrar todos eles e correlacionar?If you are writing telemetry data and logs to more than one location, can the dashboard show all of them and correlate? O dashboard de monitorização deve mostrar pelo menos, as seguintes informações:The monitoring dashboard should show at least the following information:

  • Alocação de recursos gerais para a capacidade e o crescimento.Overall resource allocation for capacity and growth. Isto inclui o número de contentores, as métricas do sistema de ficheiros, rede e alocação de núcleo.This includes the number of containers, file system metrics, network, and core allocation.
  • Métricas de contentor correlacionado no nível de serviço.Container metrics correlated at the service level.
  • As métricas do sistema correlacionadas com contentores.System metrics correlated with containers.
  • Erros de serviço e valores atípicos.Service errors and outliers.

Rastreio distribuídoDistributed tracing

Conforme mencionado, um desafio em microsserviços é entender o fluxo de eventos entre serviços.As mentioned, one challenge in microservices is understanding the flow of events across services. Uma única operação ou a transação pode envolver chamadas para vários serviços.A single operation or transaction may involve calls to multiple services. Para reconstruir a sequência inteira de passos, cada serviço deve propagar uma ID de correlação que age como um identificador exclusivo para essa operação.To reconstruct the entire sequence of steps, each service should propagate a correlation ID that acts as a unique identifier for that operation. O ID de correlação permite que distribuído rastreio em todos os serviços.The correlation ID enables distributed tracing across services.

O primeiro serviço que recebe um pedido de cliente deve gerar o ID de correlação.The first service that receives a client request should generate the correlation ID. Se o serviço faz uma chamada HTTP para outro serviço, ele coloca o ID de correlação num cabeçalho de pedido.If the service makes an HTTP call to another service, it puts the correlation ID in a request header. Da mesma forma, se o serviço envia uma mensagem assíncrona, coloca o ID de correlação na mensagem.Similarly, if the service sends an asynchronous message, it puts the correlation ID into the message. Serviços Downstream continuam propagar o ID de correlação, para que fluem através de todo o sistema.Downstream services continue to propagate the correlation ID, so that it flows through the entire system. Além disso, todo o código que escreve eventos de métricas ou de registo de aplicação deve incluir o ID de correlação.In addition, all code that writes application metrics or log events should include the correlation ID.

Quando são correlacionadas chamadas de serviço, pode calcular a métricas operacionais, como a latência de ponto-a-ponto para uma transação completa, o número de transações com êxito por segundo e a percentagem de transações falhadas.When service calls are correlated, you can calculate operational metrics such as the end-to-end latency for a complete transaction, the number of successful transactions per second, and the percentage of failed transactions. Incluindo IDs de correlação de registos de aplicações torna possível realizar a análise da causa raiz.Including correlation IDs in application logs makes it possible to perform root cause analysis. Se uma operação falhar, pode encontrar instruções do log de todas as chamadas de serviço que faziam parte da mesma operação.If an operation fails, you can find the log statements for all of the service calls that were part of the same operation.

Aqui estão algumas considerações quando implementar o rastreio distribuído:Here are some considerations when implementing distributed tracing:

  • Atualmente, não existe nenhum cabeçalho HTTP padrão para IDs de correlação.There is currently no standard HTTP header for correlation IDs. Sua equipe deve padronizar num valor de cabeçalho personalizado.Your team should standardize on a custom header value. A opção poderá ser decidida por sua estrutura de monitorização/registo ou escolha de malha do serviço.The choice may be decided by your logging/monitoring framework or choice of service mesh.

  • Para mensagens assíncronas, se sua infra-estrutura de mensagens oferece suporte a adição de metadados para mensagens, deve incluir o ID de correlação de como metadados.For asynchronous messages, if your messaging infrastructure supports adding metadata to messages, you should include the correlation ID as metadata. Caso contrário, incluí-lo como parte do esquema de mensagem.Otherwise, include it as part of the message schema.

  • Em vez de um identificador opaco único, pode enviar um contexto de correlação que inclui informações mais detalhadas, como relações de chamador receptor.Rather than a single opaque identifier, you might send a correlation context that includes richer information, such as caller-callee relationships.

  • O Azure Application Insights SDK injeta o contexto de correlação no cabeçalhos HTTP automaticamente e inclui o ID de correlação de registos do Application Insights.The Azure Application Insights SDK automatically injects correlation context into HTTP headers, and includes the correlation ID in Application Insights logs. Se optar por utilizar as funcionalidades de correlação incorporadas no Application Insights, alguns serviços ainda poderão ter de propagar explicitamente os cabeçalhos de correlação, consoante as bibliotecas que está a ser utilizados.If you decide to use the correlation features built into Application Insights, some services may still need to explicitly propagate the correlation headers, depending on the libraries being used. Para obter mais informações, consulte correlação de telemetria no Application Insights.For more information, see Telemetry correlation in Application Insights.

  • Se estiver a utilizar Istio ou linkerd como uma malha de serviço, essas tecnologias geram automaticamente cabeçalhos de correlação quando chamadas HTTP são encaminhadas por meio de proxies de malha do serviço.If you are using Istio or linkerd as a service mesh, these technologies automatically generate correlation headers when HTTP calls are routed through the service mesh proxies. Serviços devem encaminhar os cabeçalhos relevantes.Services should forward the relevant headers.

  • Considere como vai irá agregar registos.Consider how you will aggregate logs. Poderá pretender padronizar das equipes como incluir IDs de correlação nos registos.You may want to standardize across teams on how to include correlation IDs in logs. Utilize um formato estruturado ou semiestruturados, tais como JSON e defina um campo comum para conter o ID de correlação.Use a structured or semi-structured format, such as JSON, and define a common field to hold the correlation ID.

Opções de tecnologiaTechnology options

O Application Insights é um serviço gerido no Azure que ingere e armazena dados de telemetria e fornece ferramentas para analisar e pesquisar os dados.Application Insights is a managed service in Azure that ingests and stores telemetry data, and provides tools for analyzing and searching the data. Para utilizar o Application Insights, instalar um pacote de instrumentação na sua aplicação.To use Application Insights, you install an instrumentation package in your application. Este pacote monitoriza a aplicação e envia dados de telemetria para o serviço do Application Insights.This package monitors the app and sends telemetry data to the Application Insights service. Ele também pode extrair dados de telemetria a partir do ambiente anfitrião.It can also pull telemetry data from the host environment. O Application Insights fornece correlação incorporada e rastreamento de dependências.Application Insights provides built-in correlation and dependency tracking. Permite-lhe controlar as métricas do sistema, métricas da aplicação e métricas de serviço do Azure, tudo num único local.It lets you track system metrics, application metrics, and Azure service metrics, all in one place.

Lembre-se de que o Application Insights regula se a taxa de dados exceder um limite máximo; Para obter detalhes, consulte limita do Application Insights.Be aware that Application Insights throttles if the data rate exceeds a maximum limit; for details, see Application Insights limits. Uma única operação pode gerar vários eventos de telemetria, portanto, se a aplicação apresentar um grande volume de tráfego, é provável que são limitados.A single operation may generate several telemetry events, so if the application experiences a high volume of traffic, it is likely to get throttled. Para atenuar este problema, pode executar a amostragem para reduzir o tráfego de telemetria.To mitigate this problem, you can perform sampling to reduce the telemetry traffic. A desvantagem é que as suas métricas serão menos precisas.The tradeoff is that your metrics will be less precise. Para obter mais informações, consulte amostragem no Application Insights.For more information, see Sampling in Application Insights. Também pode reduzir o volume de dados, as métricas de pré-agregar — ou seja, o cálculo estatísticos valores como média e o desvio-padrão e enviar esses valores em vez da telemetria não processada.You can also reduce the data volume by pre-aggregating metrics — that is, calculating statistical values such as average and standard deviation, and sending those values instead of the raw telemetry. A seguinte mensagem de blogue descreve uma abordagem para usar o Application Insights à escala: Monitorização do Azure e análises em escala.The following blog post describes an approach to using Application Insights at scale: Azure Monitoring and Analytics at Scale.

Além disso, certifique-se de que compreende o modelo de preços do Application Insights, uma vez que é cobrado com base no volume de dados.In addition, make sure that you understand the pricing model for Application Insights, because you are charged based on data volume. Para obter mais informações, consulte gerir preços e volumes de dados no Application Insights.For more information, see Manage pricing and data volume in Application Insights. Se seu aplicativo gera um grande volume de telemetria e não quiser fazer amostragem ou agregação dos dados, em seguida, Application Insights pode não ser a escolha apropriada.If your application generates a large volume of telemetry, and you don't wish to perform sampling or aggregation of the data, then Application Insights may not be the appropriate choice.

Se o Application Insights não cumpre os requisitos, aqui estão algumas abordagens sugeridas que utilizam tecnologias de código aberto populares.If Application Insights doesn't meet your requirements, here are some suggested approaches that use popular open-source technologies.

Para métricas do sistema e um contentor, considerar a exportação, tal como métricas para uma base de dados de séries temporais Prometheus ou InfluxDB em execução no cluster.For system and container metrics, consider exporting metrics to a time-series database such as Prometheus or InfluxDB running in the cluster.

  • InfluxDB é um sistema baseado em push.InfluxDB is a push-based system. Precisa de um agente enviar por push as métricas.An agent needs to push the metrics. Pode usar Heapster, que é um serviço que recolhe métricas de todo o cluster de kubelet, agrega os dados e envia-o para InfluxDB ou outra solução de armazenamento da série de tempo.You can use Heapster, which is a service that collects cluster-wide metrics from kubelet, aggregates the data, and pushes it to InfluxDB or other time-series storage solution. O Azure Container Service implementa Heapster como parte da configuração do cluster.Azure Container Service deploys Heapster as part of the cluster setup. Outra opção é Telegraf, que é um agente para recolher e métricas de relatórios.Another option is Telegraf, which is an agent for collecting and reporting metrics.

  • Prometheus é um sistema baseado em extração.Prometheus is a pull-based system. Ele scrapes periodicamente as métricas de localizações configuradas.It periodically scrapes metrics from configured locations. Prometheus pode extrair métricas geradas por cAdvisor ou métricas de estado do kube.Prometheus can scrape metrics generated by cAdvisor or kube-state-metrics. [métricas de estado de kube] kube-state-metrics é um serviço que recolhe métricas do servidor de API do Kubernetes e disponibiliza-os para Prometheus (ou um scraper compatível com um ponto de extremidade do cliente de Prometheus).kube-state-metrics is a service that collects metrics from the Kubernetes API server and makes them available to Prometheus (or a scraper that is compatible with a Prometheus client endpoint). Ao passo que Heapster agrega as métricas que o Kubernetes gera e reencaminha-os para um sink, métricas de estado de kube gera seu próprio métricas e disponibiliza-os através de um ponto final para captura.Whereas Heapster aggregates metrics that Kubernetes generates and forwards them to a sink, kube-state-metrics generates its own metrics and makes them available through an endpoint for scraping. Para as métricas do sistema, utilize principal exportadora de nó, que é uma principal exportadora de Prometheus para as métricas do sistema.For system metrics, use Node exporter, which is a Prometheus exporter for system metrics. Suporta a Prometheus ponto de dados, mas não os dados de cadeia de caracteres de vírgula flutuante, portanto, é adequada para as métricas do sistema, mas não os.Prometheus supports floating point data, but not string data, so it is appropriate for system metrics but not logs.

  • Utilizar como uma ferramenta de dashboard Kibana ou Grafana para visualizar e monitorizar os dados.Use a dashboard tool such as Kibana or Grafana to visualize and monitor the data. O serviço de dashboard também pode ser executado dentro de um contentor no cluster.The dashboard service can also run inside a container in the cluster.

Para registos de aplicações, considere a utilização Fluentd e Elasticsearch.For application logs, consider using Fluentd and Elasticsearch. Fluentd é um recoletor de dados de código-fonte aberto e Elasticsearch é um banco de dados do documento que está otimizado para atuar como um mecanismo de pesquisa.Fluentd is an open source data collector, and Elasticsearch is a document database that is optimized to act as a search engine. Com essa abordagem, cada serviço envia registos ao stdout e stderr, e Kubernetes escreve estes fluxos de sistema de arquivos local.Using this approach, each service sends logs to stdout and stderr, and Kubernetes writes these streams to the local file system. Fluentd coleta os logs, otimiza-os com metadados adicionais do Kubernetes e envia os registos para o Elasticsearch.Fluentd collects the logs, optionally enriches them with additional metadata from Kubernetes, and sends the logs to Elasticsearch. Utilize uma ferramenta semelhante, o Grafana ou Kibana para criar um dashboard para o Elasticsearch.Use Kibana, Grafana, or a similar tool to create a dashboard for Elasticsearch. Fluentd é executado como um daemonset do cluster, o que garante que um pod de Fluentd é atribuído a cada nó.Fluentd runs as a daemonset in the cluster, which ensures that one Fluentd pod is assigned to each node. Pode configurar Fluentd para recolher registos kubelet, bem como os registos de contentor.You can configure Fluentd to collect kubelet logs as well as container logs. Em grandes volumes, escrever registos no sistema de arquivos local poderia se tornar um afunilamento de desempenho, especialmente quando vários serviços em execução no mesmo nó.At high volumes, writing logs to the local file system could become a performance bottleneck, especially when multiple services are running on the same node. Monitorizar a utilização de sistema de latência e o ficheiro de disco em produção.Monitor disk latency and file system utilization in production.

Uma vantagem de usar Fluentd elasticsearch para os registos é que os serviços não necessitam de quaisquer dependências da biblioteca adicionais.One advantage of using Fluentd with Elasticsearch for logs is that services do not require any additional library dependencies. Cada serviço simplesmente escreve stdout e stderre os identificadores de Fluentd exportar os registos para o Elasticsearch.Each service just writes to stdout and stderr, and Fluentd handles exporting the logs into Elasticsearch. Além disso, as equipes de criação de serviços não precisam de compreender como configurar a infra-estrutura de log.Also, the teams writing services don't need to understand how to configure the logging infrastructure. Um desafio é configurar o cluster de Elasticsearch para uma implementação de produção, para que o dimensionamento para processar o tráfego.One challenge is to configure the Elasticsearch cluster for a production deployment, so that it scales to handle your traffic.

Outra opção consiste em enviar registos para o Log Analytics do Operations Management Suite (OMS).Another option is to send logs to Operations Management Suite (OMS) Log Analytics. O [do Log Analytics] log-analytics recolhe dados de registo de serviço para um repositório central e também pode consolidar os dados de outros serviços do Azure que utiliza o seu aplicativo.The Log Analytics service collects log data into a central repository, and can also consolidate data from other Azure services that your application uses. Para obter mais informações, consulte monitorizar um cluster do Azure Container Service com o Microsoft Operations Management Suite (OMS).For more information, see Monitor an Azure Container Service cluster with Microsoft Operations Management Suite (OMS).

Exemplo: Iniciar sessão com o IDs de correlaçãoExample: Logging with correlation IDs

Para ilustrar alguns dos pontos de discutidos neste capítulo, eis um exemplo expandido de como o serviço de pacote implementa o registo.To illustrate some of the points discussed in this chapter, here is an extended example of how the Package service implements logging. O serviço de pacote foi escrito em TypeScript e utiliza a Koa arquitetura web para node. js.The Package service was written in TypeScript and uses the Koa web framework for Node.js. Existem várias bibliotecas de Registro em log de node. js à sua escolha.There are several Node.js logging libraries to choose from. Escolhemos Winston, uma biblioteca de registo mais populares que cumprem os nossos requisitos de desempenho quando Testamos.We picked Winston, a popular logging library that met our performance requirements when we tested it.

Para encapsular os detalhes da implementação, definimos um resumo ILogger interface:To encapsulate the implementation details, we defined an abstract ILogger interface:

export interface ILogger {
    log(level: string, msg: string, meta?: any)
    debug(msg: string, meta?: any)
    info(msg: string, meta?: any)
    warn(msg: string, meta?: any)
    error(msg: string, meta?: any)
}

Aqui está um ILogger implementação que encapsula num wrapper a biblioteca de Winston.Here is an ILogger implementation that wraps the Winston library. Ele usa o ID de correlação como um parâmetro de construtor e injeta o ID no todas as mensagens de registo.It takes the correlation ID as a constructor parameter, and injects the ID into every log message.

class WinstonLogger implements ILogger {
    constructor(private correlationId: string) {}
    log(level: string, msg: string, payload?: any) {
        var meta : any = {};
        if (payload) { meta.payload = payload };
        if (this.correlationId) { meta.correlationId = this.correlationId }
        winston.log(level, msg, meta)
    }
  
    info(msg: string, payload?: any) {
        this.log('info', msg, payload);
    }
    debug(msg: string, payload?: any) {
        this.log('debug', msg, payload);
    }
    warn(msg: string, payload?: any) {
        this.log('warn', msg, payload);
    }
    error(msg: string, payload?: any) {
        this.log('error', msg, payload);
    }
}

O serviço de pacote precisa extrair o ID de correlação de pedido HTTP.The Package service needs to extract the correlation ID from the HTTP request. Por exemplo, se estiver a utilizar linkerd, o ID de correlação é encontrado no l5d-ctx-trace cabeçalho.For example, if you're using linkerd, the correlation ID is found in the l5d-ctx-trace header. Koa, o pedido HTTP é armazenado num objeto de contexto passa a pipeline de processamento de solicitação.In Koa, the HTTP request is stored in a Context object that gets passed through the request processing pipeline. Podemos definir uma função de middleware para obter o ID de correlação de contexto e inicializar o agente de log.We can define a middleware function to get the correlation ID from the Context and initialize the logger. (É simplesmente uma função que é executada para cada solicitação de uma função de middleware Koa.)(A middleware function in Koa is simply a function that gets executed for each request.)

export type CorrelationIdFn = (ctx: Context) => string;

export function logger(level: string, getCorrelationId: CorrelationIdFn) {
    winston.configure({
        level: level,
        transports: [new (winston.transports.Console)()]
        });
    return async function(ctx: any, next: any) {
        ctx.state.logger = new WinstonLogger(getCorrelationId(ctx));
        await next();
    }
}

Este middleware invoca uma função definida pelo chamador, getCorrelationId, para obter o ID de correlação.This middleware invokes a caller-defined function, getCorrelationId, to get the correlation ID. Em seguida, ele cria uma instância de agente e stashes-lo no ctx.state, que é um dicionário de chave-valor usado em Koa para passar informações através do pipeline.Then it creates an instance of the logger and stashes it inside ctx.state, which is a key-value dictionary used in Koa to pass information through the pipeline.

O middleware de agente de log é adicionado para o pipeline na inicialização:The logger middleware is added to the pipeline on startup:

app.use(logger(Settings.logLevel(), function (ctx) {
    return ctx.headers[Settings.correlationHeader()];  
}));

Quando tudo estiver configurada, é fácil adicionar instruções de registro no código.Once everything is configured, it's easy to add logging statements to the code. Por exemplo, aqui está o método que procura um pacote.For example, here is the method that looks up a package. Ele faz duas chamadas para o ILogger.info método.It makes two calls to the ILogger.info method.

async getById(ctx: any, next: any) {
  var logger : ILogger = ctx.state.logger;
  var packageId = ctx.params.packageId;
  logger.info('Entering getById, packageId = %s', packageId);

  await next();

  let pkg = await this.repository.findPackage(ctx.params.packageId)

  if (pkg == null) {
    logger.info(`getById: %s not found`, packageId);
    ctx.response.status= 404;
    return;
  }

  ctx.response.status = 200;
  ctx.response.body = this.mapPackageDbToApi(pkg);
}

Não precisamos incluir o ID de correlação nas instruções de Registro em log, porque isso é feito automaticamente pela função middleware.We don't need to include the correlation ID in the logging statements, because that's done automatically by the middleware function. Isso torna o código de registo mais limpo e reduz a possibilidade de que um desenvolvedor se esqueça de incluir o ID de correlação.This makes the logging code cleaner, and reduces the chance that a developer will forget to include the correlation ID. E porque todas as instruções de Registro em log usam a abstração da ILogger interface, seria fácil substituir a implementação de agente de log mais tarde.And because all of the logging statements use the abstract ILogger interface, it would be easy to replace the logger implementation later.