Introdução ao Kinesis Agent para plug-ins do Windows Implementando fábricas de plugins do Kinesis Agent para Windows Implementando origens de plug-in do Kinesis Agent para Windows Implementação de pias de plug-in do Kinesis Agent para Windows

Criação de plug-ins do Kinesis Agent para Windows

Para a maioria das situações, não é necessário criar um plug-in do Amazon Kinesis Agent para Microsoft Windows. O Kinesis Agent para Windows é altamente configurável e contém origens e coletores avançados, comoDirectorySourceeKinesisStream, que são suficientes para a maioria dos cenários. Para obter detalhes sobre as origens e os coletores existentes, consulte Configurando o Amazon Kinesis Agent para Microsoft Windows.

Para cenários incomuns, pode ser necessário estender o Kinesis Agent para Windows usando um plug-in personalizado. Alguns desses cenários incluem o seguinte:

Empacotar uma declaração DirectorySource complexa usando os analisadores de registros Delimited ou Regex para que seja fácil aplicar em muitos tipos diferentes de arquivos de configuração.
Criar uma nova origem que não seja baseada em arquivos ou que exceda os recursos de análise fornecidos pelo analisadores de registros existentes.
Criar um coletor para um serviço da AWS que atualmente não seja compatível.

Tópicos

Introdução ao Kinesis Agent para plug-ins do Windows
Implementando fábricas de plugins do Kinesis Agent para Windows
Implementando origens de plug-in do Kinesis Agent para Windows
Implementação de pias de plug-in do Kinesis Agent para Windows

Introdução ao Kinesis Agent para plug-ins do Windows

Não há nada de especial com plug-ins personalizados. Todas as origens e coletores existentes usam os mesmos mecanismos que os plug-ins personalizados usam para serem carregados quando o Kinesis Agent para Windows é iniciado, e eles instanciam plug-ins relevantes depois de ler aappsettings.jsonArquivo de configuração.

Quando o Kinesis Agent para Windows é iniciado, ocorre a seguinte sequência:

O Kinesis Agent para Windows examina as montagens no diretório de instalação (%PROGRAMFILES%\Amazon\AWSKinesisTap) para classes que implementam oIFactory<T>definida na interfaceAmazon.KinesisTap.CoreAssembly. Essa interface é definida emAmazon.KinesisTap.Core\Infrastructure\IFactory.csno código-fonte do Kinesis Agent para Windows.
O Kinesis Agent para Windows carrega as montagens que contêm essas classes e invoca a propriedadeRegisterFactorynessas classes.
O Kinesis Agent para Windows carrega oappsettings.jsonArquivo de configuração. Para cada origem e coletor no arquivo de configuração, os pares de chave-valor SourceType e SinkType são examinados. Se houver fábricas registradas com o mesmo nome que os valores dos pares de chave-valor SourceType e SinkType, o método CreateInstance é invocado nessas fábricas. O método CreateInstance transmite a configuração e outras informações como um objeto IPluginContext. O método CreateInstance é responsável por configurar e inicializar o plug-in.

Para um plug-in funcionar corretamente, deve haver uma classe de fábrica registrada que crie o plug-in, e a classe do plug-in deve ser definida.

O código-fonte do Kinesis Agent para Windows está localizado emhttps://github.com/awslabs/kinesis-agent-windows.

Implementando fábricas de plugins do Kinesis Agent para Windows

Siga estas etapas para implementar uma fábrica de plug-ins do Kinesis Agent para Windows.

Para criar uma fábrica de plugins do Kinesis Agent para Windows

Crie um projeto de biblioteca C# direcionado para .NET Framework 4.6.
Adicione uma referência ao conjunto Amazon.KinesisTap.Core. Esse conjunto está localizado no%PROGRAMFILES%\Amazon\AWSKinesisTapapós a instalação do Kinesis Agent para Windows.
Use NuGet para instalar o pacote Microsoft.Extensions.Configuration.Abstractions.
Use NuGet para instalar o pacote System.Reactive.
Use NuGet para instalar o pacote Microsoft.Extensions.Logging.

Crie uma classe de fábrica que implemente IFactory<IEventSource> para origens ou IFactory<IEventSink> para coletores. Adicione os métodos RegisterFactory e CreateInstance.

Por exemplo, o código a seguir cria uma fábrica de plug-ins do Kinesis Agent para Windows que cria uma origem que gera dados aleatórios:


using System;
using Amazon.KinesisTap.Core;
using Microsoft.Extensions.Configuration;

namespace MyCompany.MySources
{
    public class RandomSourceFactory : IFactory<ISource>
    {
        public void RegisterFactory(IFactoryCatalog<ISource> catalog)
        {
            catalog.RegisterFactory("randomsource", this);
        }

        public ISource CreateInstance(string entry, IPlugInContext context)
        {
            IConfiguration config = context.Configuration;

            switch (entry.ToLower())
            {
                case "randomsource":
                    string rateString = config["Rate"];
                    string maxString = config["Max"];
                    TimeSpan rate;
                    int max;

                    if (string.IsNullOrWhiteSpace(rateString))
                    {
                        rate = TimeSpan.FromSeconds(30);
                    }
                    else
                    {
                        if (!TimeSpan.TryParse(rateString, out rate))
                        {
                            throw new Exception($"Rate {rateString} is invalid for RandomSource.");
                        }
                    }
 
                    if (string.IsNullOrWhiteSpace(maxString))
                    {
                        max = 1000;
                    }
                    else
                    {
                        if (!int.TryParse(maxString, out max))
                        {
                            throw new Exception($"Max {maxString} is invalid for RandomSource.");
                        }
                    }

                    return new RandomSource(rate, max, context);
                default:
                    throw new ArgumentException($"Source {entry} is not recognized.", entry);
            }
        }
    }
}

A instrução switch é usada no método CreateInstance caso você deseje aprimorar a fábrica para criar diferentes tipos de instâncias.

Para criar uma fábrica de coletores que crie um coletor que não faz nada, use uma classe semelhante à seguinte:


using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Amazon.KinesisTap.Core;
using Microsoft.Extensions.Configuration;

namespace MyCompany.MySinks 
{
    public class NullSinkFactory : IFactory<IEventSink>
    {
        public void RegisterFactory(IFactoryCatalog<IEventSink> catalog)
        {
            catalog.RegisterFactory("nullsink", this);
        }

        public IEventSink CreateInstance(string entry, IPlugInContext context)
        {
            IConfiguration config = context.Configuration;

            switch (entry.ToLower())
            {
                case "nullsink":
                    return new NullSink(context);
                default:
                    throw new Exception("Unrecognized sink type {entry}.");
            }
        }
    }
}

Implementando origens de plug-in do Kinesis Agent para Windows

Siga estas etapas para implementar uma origem de plug-ins do Kinesis Agent para Windows.

Para criar uma fonte de plug-in do Kinesis Agent para Windows

Adicione uma classe que implemente a interface IEventSource<out T> ao projeto criado anteriormente para a origem.

Por exemplo, use o código a seguir para definir uma origem que gere dados aleatórios:


using System;
using System.Reactive.Subjects;
using System.Timers;
using Amazon.KinesisTap.Core;
using Microsoft.Extensions.Logging;

namespace MyCompany.MySources
{
    public class RandomSource : EventSource<RandomData>, IDisposable
    {
        private TimeSpan _rate;
        private int _max;
        private Timer _timer = null;
        private Random _random = new Random();
        private ISubject<IEnvelope<RandomData>> _recordSubject = new Subject<IEnvelope<RandomData>>();
        


        public RandomSource(TimeSpan rate, int max, IPlugInContext context) : base(context)
        {
            _rate = rate;
            _max = max;
        }

        public override void Start()
        {
            try
            {
                CleanupTimer();
                _timer = new Timer(_rate.TotalMilliseconds);
                _timer.Elapsed += (Object source, ElapsedEventArgs args) =>
                {
                    var data = new RandomData()
                    {
                        RandomValue = _random.Next(_max)
                    };
                    _recordSubject.OnNext(new Envelope<RandomData>(data));
                };
                _timer.AutoReset = true;
                _timer.Enabled = true;
                _logger?.LogInformation($"Random source id {this.Id} started with rate {_rate.TotalMilliseconds}.");
            }
            catch (Exception e)
            {
                _logger?.LogError($"Exception during start of RandomSource id {this.Id}: {e}");
            }
        }

        public override void Stop()
        {
            try
            {
                CleanupTimer();
                _logger?.LogInformation($"Random source id {this.Id} stopped.");                
            }
            catch (Exception e)
            {
                _logger?.LogError($"Exception during stop of RandomSource id {this.Id}: {e}");
            }
        }

        private void CleanupTimer()
        {
            if (_timer != null)
            {
                _timer.Enabled = false;
                _timer?.Dispose();
                _timer = null;
            }
        }

        public override IDisposable Subscribe(IObserver<IEnvelope<RandomData>> observer)
        {
            return this._recordSubject.Subscribe(observer);
        }

        public void Dispose()
        {
            CleanupTimer();
        }
    }
}

Neste exemplo, a classe RandomSource é herdada da classe EventSource<T>, pois ela fornece a propriedade Id. Embora este exemplo não ofereça suporte a marcadores, essa classe básica também é útil para implementar essa funcionalidade. Os envelopes fornecem uma maneira de armazenar metadados e encapsular dados arbitrários para o streaming para coletores. A classe RandomData é definida na próxima etapa e representa o tipo de objeto de saída a partir dessa origem.

Adicione uma classe ao projeto definido anteriormente que contém os dados que são transmitidos por streaming a partir da origem.

Por exemplo, um contêiner de dados aleatórios poderia ser definido da seguinte forma:
```
namespace MyCompany.MySources
{
    public class RandomData
    {
        public int RandomValue { get; set; }
    }
}               
```
Compile o projeto definido anteriormente.
Copie o conjunto no diretório de instalação do Kinesis Agent para Windows.
Crie ou atualize umappsettings.jsonque use a nova origem e coloque-a no diretório de instalação do Kinesis Agent para Windows.
Interrompa e inicie o Kinesis Agent para Windows.
Verifique o arquivo de log atual do Kinesis Agent para Windows (geralmente localizado na seção%PROGRAMDATA%\Amazon\AWSKinesisTap\logs) para garantir que não haja problemas com o plug-in de origem personalizado.
Certifique-se de que os dados estejam chegando ao serviço da AWS desejado.

Para obter um exemplo de como estender oDirectorySourcePara implementar a análise de um formato de log, consulteAmazon.KinesisTap.Uls\UlsSourceFactory.cseAmazon.KinesisTap.Uls\UlsLogParser.csno código-fonte do Kinesis Agent para Windows.

Para obter um exemplo de como criar uma origem que forneça a funcionalidade de marcação, consulteAmazon.KinesisTap.Windows\WindowsSourceFactory.cseAmazon.KinesisTap.Windows\EventLogSource.csno código-fonte do Kinesis Agent para Windows.

Implementação de pias de plug-in do Kinesis Agent para Windows

Siga estas etapas para implementar um coletor de plug-ins do Kinesis Agent para Windows.

Para criar um coletor de plugins do Kinesis Agent para Windows

Adicione uma classe ao projeto definido anteriormente que implemente a interface IEventSink.

Por exemplo, o código a seguir implementa um coletor que não faz nada que não seja registrar a chegada de registros que depois são descartados.


using Amazon.KinesisTap.Core;
using Microsoft.Extensions.Logging;

namespace MyCompany.MySinks
{
    public class NullSink : EventSink
    {
        public NullSink(IPlugInContext context) : base(context)
        {
        }

        public override void OnNext(IEnvelope envelope)
        {
            _logger.LogInformation($"Null sink {Id} received {GetRecord(envelope)}.");
        }

        public override void Start()
        {
            _logger.LogInformation($"Null sink {Id} starting.");
        }

        public override void Stop()
        {
            _logger.LogInformation($"Null sink {Id} stopped.");
        }
    }
}

Nesse exemplo, a classe de coletor NullSink é herdada da classe EventSink, pois ela fornece a capacidade de transformar registros em diferentes formatos de serialização, como JSON e XML.

Compile o projeto definido anteriormente.
Copie o conjunto no diretório de instalação do Kinesis Agent para Windows.
Crie ou atualize umappsettings.jsonque use o novo coletor e coloque-o no diretório de instalação do Kinesis Agent para Windows. Por exemplo, para usar os plug-ins personalizados RandomSource e NullSink, você pode usar o seguinte arquivo de configuração appsettings.json:
```
{
  "Sources": [
  {
	"Id": "MyRandomSource",
	"SourceType": "RandomSource",
	"Rate": "00:00:10",
	"Max": 50
  }
    
  ],
  "Sinks": [
  {
    "Id": "MyNullSink",
	"SinkType": "NullSink",
	"Format": "json"
  }
  ],
  "Pipes": [
    {
	  "Id": "MyRandomToNullPipe",
	  "SourceRef": "MyRandomSource",
	  "SinkRef": "MyNullSink"
	}
  ]
}               
```
Essa configuração cria uma origem que envia uma instância de RandomData com um RandomValue definido como um número aleatório entre 0 e 50 a cada 10 segundos. Ele cria um coletor que transforma as instâncias RandomData de entrada em JSON, registra esse JSON e descarta as instâncias. Certifique-se de incluir os dois exemplos de fábricas, a classe de origem RandomSource e a classe de coletor NullSink no projeto definido anteriormente para usar o arquivo de configuração de exemplo.
Interrompa e inicie o Kinesis Agent para Windows.
Verifique o arquivo de log atual do Kinesis Agent para Windows (geralmente localizado na seção%PROGRAMDATA%\Amazon\AWSKinesisTap\logs) para garantir que não haja problemas com o plug-in de coletor personalizado.

Certifique-se de que os dados estejam chegando ao serviço da AWS desejado. Como o exemplo de NullSink não faz streaming para um serviço da AWS, você pode verificar o funcionamento correto do coletor procurando as mensagens de log que indicam que os registros foram recebidos.

Por exemplo, você pode ver um arquivo de log semelhante ao seguinte:


2018-10-18 12:36:36.3647 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.AWS.AWSEventSinkFactory.
2018-10-18 12:36:36.4018 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.Windows.PerformanceCounterSinkFactory.
2018-10-18 12:36:36.4018 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory MyCompany.MySinks.NullSinkFactory.
2018-10-18 12:36:36.6926 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.Core.DirectorySourceFactory.
2018-10-18 12:36:36.6926 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.ExchangeSource.ExchangeSourceFactory.
2018-10-18 12:36:36.6926 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.Uls.UlsSourceFactory.
2018-10-18 12:36:36.6926 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.Windows.WindowsSourceFactory.
2018-10-18 12:36:36.6926 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory MyCompany.MySources.RandomSourceFactory.
2018-10-18 12:36:36.9601 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.Core.Pipes.PipeFactory.
2018-10-18 12:36:37.4694 Amazon.KinesisTap.Hosting.LogManager INFO Registered factory Amazon.KinesisTap.AutoUpdate.AutoUpdateFactory.
2018-10-18 12:36:37.4807 Amazon.KinesisTap.Hosting.LogManager INFO Performance counter sink  started.
2018-10-18 12:36:37.6250 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink starting.
2018-10-18 12:36:37.6250 Amazon.KinesisTap.Hosting.LogManager INFO Connected source MyRandomSource to sink MyNullSink
2018-10-18 12:36:37.6333 Amazon.KinesisTap.Hosting.LogManager INFO Random source id MyRandomSource started with rate 10000.
2018-10-18 12:36:47.8084 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":14}.
2018-10-18 12:36:57.6339 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":5}.
2018-10-18 12:37:07.6490 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":9}.
2018-10-18 12:37:17.6494 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":47}.
2018-10-18 12:37:27.6520 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":25}.
2018-10-18 12:37:37.6676 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":21}.
2018-10-18 12:37:47.6688 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":29}.
2018-10-18 12:37:57.6700 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":22}.
2018-10-18 12:38:07.6838 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":32}.
2018-10-18 12:38:17.6848 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":12}.
2018-10-18 12:38:27.6866 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":46}.
2018-10-18 12:38:37.6880 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":48}.
2018-10-18 12:38:47.6893 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":39}.
2018-10-18 12:38:57.6906 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":18}.
2018-10-18 12:39:07.6995 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":6}.
2018-10-18 12:39:17.7004 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":0}.
2018-10-18 12:39:27.7021 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":3}.
2018-10-18 12:39:37.7023 Amazon.KinesisTap.Hosting.LogManager INFO Null sink MyNullSink received {"RandomValue":19}.

Se você estiver criando um coletor que acesse os serviços da AWS, há classes básicas que podem ser úteis. Para um dissipador que usa oAWSBufferedEventSinkclasse base, consulteAmazon.KinesisTap.AWS\CloudWatchLogsSink.csno código-fonte do Kinesis Agent para Windows.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Solução de problemas

Histórico do documento