logstash-output-azure_event_hubs 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8d1ae4dbc16152ca2c3f2aa566aa21e343a9dee8baf1373ff74b444814eac990
+  data.tar.gz: 21074907a28e05132fc8d15d19caf16de11daeb3bb9d446361320da0e8a94b1c
+SHA512:
+  metadata.gz: 2755e3b5b8f9a8c782da650435e5a58c0713de9a60dd7b55dc51399f2717cae1c5a4353b84ec0f778e0dc3d25c88b2c759fdd3c8877df86ef9d6c189ef7e3b85
+  data.tar.gz: 68a7a595d8c673c53fb31d82e4381b8c2e3bab8031f99a8f82978a785972639c20e80fbc009a10cd5684173a672dbc126d42607644ecde4410b1a23c5584db33

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+All notable changes to this project will be documented in this file. Format is based on [Keep a Changelog]( https://keepachangelog.com/en/1.0.0/ ).
+This project adheres to [Semantic Versioning]( https://semver.org/ ).
+
+
+## \[Unreleased\]
+### Added
+### Changed
+### Deprecated
+### Removed
+### Fixed
+### Security
+
+***
+
+## \[0.1.0\]  2019-06-11
+### Added
+- Plugin created

data/CONTRIBUTORS

@@ -0,0 +1,11 @@
+The following is a list of people who have contributed ideas, code, bug
+reports, or in general have helped Logstash along its way.
+
+Contributors:
+* Bryan K Lewis (@bryanklewis)
+* James Davison III (@jedthe3rd)
+
+Note: If you've sent us patches, bug reports, or otherwise contributed to
+Logstash, and you aren't on the list above and want to be, please let us know
+and we'll make sure you're here. Contributions from folks like you are what make
+open source awesome.

data/Gemfile

@@ -0,0 +1,11 @@
+source 'https://rubygems.org'
+
+gemspec
+
+logstash_path = ENV["LOGSTASH_PATH"] || "../../logstash"
+use_logstash_source = ENV["LOGSTASH_SOURCE"] && ENV["LOGSTASH_SOURCE"].to_s == "1"
+
+if Dir.exist?(logstash_path) && use_logstash_source
+  gem 'logstash-core', :path => "#{logstash_path}/logstash-core"
+  gem 'logstash-core-plugin-api', :path => "#{logstash_path}/logstash-core-plugin-api"
+end

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2019 Micron Technology, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/NOTICE

@@ -0,0 +1,52 @@
+Acknowledgments
+
+Portions of the plugin may utilize the following copyrighted material,
+the use of which is hereby acknowledged.
+
+##############################################################################
+# Logstash Sample Plugin / Plugin Generator                                  #
+# Logstash Input Azure Event Hubs                                            #
+# Logstash Output Kafka Plugin                                               #
+##############################################################################
+
+https://github.com/logstash-plugins/logstash-output-example
+https://github.com/logstash-plugins/logstash-input-azure_event_hubs
+https://github.com/logstash-plugins/logstash-output-kafka
+
+--------------------------------------------------------------
+Copyright (c) 2012-2018 Elasticsearch <http://www.elastic.co>
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+
+##############################################################################
+# Logstash Output Kusto Plugin                                               #
+##############################################################################
+
+https://github.com/Azure/logstash-output-kusto
+
+--------------------------------------------------------------
+Copyright Microsoft Corporation. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+

data/README.md

@@ -0,0 +1,79 @@
+# Logstash Output Plugin for Azure Event Hubs
+
+This is a plugin for [Logstash](https://github.com/elastic/logstash). It is fully free and open source. The license is Apache 2.0.
+This plugin enables you to send events from Elastic Logstash to an Azure [Event Hubs](https://azure.microsoft.com/en-us/services/event-hubs/) entity. The Azure Event Hubs [Java SDK](https://docs.microsoft.com/en-us/java/api/com.microsoft.azure.eventhubs.eventhubclient.sendsync?view=azure-java-stable) is used to send events via synchronous class methods over AMQP.
+
+## Requirements
+
+- Java 11 JDK or JRE. Recommend the [Azul Zulu](https://www.elastic.co/guide/en/logstash/current/installing-logstash.html) OpenJDK builds.
+- Logstash version 7+. [Installation instructions](https://www.elastic.co/guide/en/logstash/current/installing-logstash.html) 
+- Azure Event Hubs namespace and hub.
+  - Read [Create an Event Hub](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-create) for more information.
+- Credentials with permission to write data into Azure Event Hubs.
+  - [Create a SAS Policy Key](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-get-connection-string) for more information on viewing your connection screen or where to create a new key.
+
+## Installation
+
+To make the Azure Event Hubs output plugin available in your Logstash environment, run the following command:
+```sh
+bin/logstash-plugin install logstash-output-azure_event_hubs
+```
+
+## Configuration
+
+Information about configuring Logstash can be found in the [Logstash configuration guide](https://www.elastic.co/guide/en/logstash/current/configuration.html).
+
+You will need to configure this plugin before sending events from Logstash to Azure Event Hubs. The following example shows the minimum you need to provide:
+
+```yaml
+output {
+    azure_event_hubs {
+        service_namespace => "myeventnamespace" #Exclude .servicebus.windows.net
+        event_hub => "logs"
+        sas_key_name => "myeventnamespace-write"
+        sas_key => '...'
+    }
+}
+```
+
+### Available Configuration Keys
+
+| Parameter Name | Description | Notes |
+| --- | --- | --- |
+| service_namespace | Azure Service Namespace or Endpoint. | Required.
+| service_uri | Use a national Azure Cloud. | 
+| event_hub | Azure Event Hub (Entity) Path. | Required
+| sas_key_name | Azure Shared Access Signature (SAS) Key Name. | Required
+| sas_key | Azure Shared Access Signature (SAS) Key. | Required
+| connection_retry_count | Number of times to retry a failed Event Hubs connection. | Default: 3
+| properties_bag | Event metadata key=value pairs to set in the user-defined property bag. See [EventData](https://docs.microsoft.com/en-us/java/api/com.microsoft.azure.eventhubs.eventdata?view=azure-java-stable) class for more information. This config can be used to route events dynamically for [Azure Data Explorer]() by setting properties: <br>```"Table" => "%{[adx_table_name]}" "Format" => "json" "IngestionMappingReference" => "adx_ingest_map"``` | Format: ```properties_bag => { "key1" => "value1" "key2" => "%{[event_field]}" }```
+| client_threads | Total threads used by Azure Event Hubs client to handle events. This value is used when creating the Java Concurrency Executor pool size. | Default: 4
+
+## Development
+
+- Jruby 9.2.6.0+
+- Java 11 JDK
+- Logstash version 7+. 
+- Azure Event Hubs namespace, hub, and credential to test against.
+- [Gradle](https://gradle.org/install/) is used to download the .jar dependencies and generate the classpath file by running:
+
+1. Install Dependencies
+```shell
+rake vendor
+bundle install
+```
+or
+```shell
+gradle vendor --info
+bundle install
+```
+
+2. Running your unpublished Plugin in Logstash
+Run in a local Logstash clone. Edit the Logstash Gemfile and add the local plugin path at the top of the Gemfile, for example:
+```
+gem 'logstash-output-azure_event_hubs', :path => '/path/to/logstash-output-azure_event_hubs'
+```
+
+## Contributing
+
+All contributions are welcome: ideas, patches, documentation, bug reports, and complaints. For more information about contributing, see the [CONTRIBUTING](https://github.com/elastic/logstash/blob/master/CONTRIBUTING.md) file.

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/logstash-output-azure_event_hubs_jars.rb

@@ -0,0 +1,7 @@
+# AUTOGENERATED BY THE GRADLE SCRIPT. DO NOT EDIT.
+
+require 'jar_dependencies'
+require_jar('org.apache.qpid', 'proton-j', '0.31.0')
+require_jar('com.microsoft.azure', 'qpid-proton-j-extensions', '1.2.0')
+require_jar('org.slf4j', 'slf4j-api', '1.7.25')
+require_jar('com.microsoft.azure', 'azure-eventhubs', '2.3.2')

data/lib/logstash/outputs/azure_event_hubs.rb

@@ -0,0 +1,170 @@
+# encoding: utf-8
+
+# Copyright 2019 Micron Technology, Inc. <https://www.micron.com/>
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# This work contains copyrighted material, see NOTICE for
+# additional copyright aknowledgements.
+
+require 'logstash-output-azure_event_hubs_jars'
+require 'logstash/outputs/base'
+require 'logstash/namespace'
+require 'logstash/errors'
+
+
+java_import com.microsoft.azure.eventhubs.ConnectionStringBuilder;
+java_import com.microsoft.azure.eventhubs.EventData;
+java_import com.microsoft.azure.eventhubs.EventHubClient;
+java_import com.microsoft.azure.eventhubs.EventHubException;
+
+java_import java.io.IOException;
+java_import java.nio.ByteBuffer;
+java_import java.nio.charset.Charset;
+java_import java.util.concurrent.ExecutionException;
+java_import java.util.concurrent.Executors;
+java_import java.util.concurrent.ScheduledExecutorService;
+
+# Output plugin to send events to an Azure Event Hub.
+class LogStash::Outputs::AzureEventHubs < LogStash::Outputs::Base
+  config_name "azure_event_hubs"
+
+  # Azure Service Namespace or Endpoint
+  config :service_namespace, :validate => :string, :required => true, :default => nil
+
+  # Azure Service URI
+  # Use a national Azure Cloud
+  config :service_uri, :validate => :string, :required => false, :default => nil
+
+  # Azure Event Hub (Entity) Path
+  config :event_hub, :validate => :string, :required => true, :default => nil
+  
+  # Azure Shared Access Signature (SAS) Key Name
+  config :sas_key_name, :validate => :string, :required => true, :default => nil
+  
+  # Azure Shared Access Signature (SAS) Key
+  config :sas_key, :validate => :string, :required => true, :default => nil
+
+  # Number of times to retry a failed Event Hubs connection
+  # Defaults to 3
+  config :connection_retry_count, :validate => :number, :required => false, :default => 3
+
+  # Properties Bag
+  # Event metadata key=value pairs to set in the user-defined property bag
+  # See the EventData class for more information
+  # https://docs.microsoft.com/en-us/java/api/com.microsoft.azure.eventhubs.eventdata?view=azure-java-stable
+  # Format: properties_bag => { "key1" => "value1" "key2" => "%{[event_field]}" }
+  config :properties_bag, :validate => :hash, :required => false, :default => nil
+
+  # Total threads used by Azure Event Hubs client to handle events
+  # Requires at minimum 2 threads
+  # Defaults to 4
+  config :client_threads, :validate => :number, :required => false, :default => 4
+
+  # Default serialize messages with JSON
+  default :codec, 'json'
+
+  public
+  def register
+    # Build Event Hubs client connection string
+    connection_builder = ConnectionStringBuilder.new()
+    connection_builder.setNamespaceName(@service_namespace)
+    connection_builder.setEventHubName(@event_hub)
+    connection_builder.setSasKeyName(@sas_key_name)
+    connection_builder.setSasKey(@sas_key)
+
+    # Configure for national cloud uri
+    if (!@service_uri.nil?)
+      connection_builder.setEndpoint(@service_uri)
+    end
+
+    # The Executor handles all the asynchronous tasks and this is passed to the EventHubClient.
+    # The gives the user control to segregate their thread pool based on the work load.
+    # This pool can then be shared across multiple EventHubClient instances.
+    @executor_service = Executors.newScheduledThreadPool(@client_threads)
+
+    # Handle Transient errors when creating the Event Hubs Client
+    try = 0
+    retry_interval = 2
+    begin
+      # Each EventHubClient instance spins up a new TCP/SSL connection, which is expensive.
+      # It is always a best practice to reuse these instances.
+      @eventhub_client = EventHubClient.createSync(connection_builder.toString(), @executor_service)
+
+    rescue EventHubException, ExecutionException, InterruptedException, IOException => e
+      # Log error, no retry
+      if e.getIsTransient() != true or e == IOException or try >= @connection_retry_count
+        @logger.error(
+          "Unable to establish connection to Azure Event Hubs.",
+          :error_message => e.getMessage(),
+          :class => e.class.name
+          )
+        close()
+        exit(1)
+      end
+
+      # Log error with retry
+      @logger.error(
+        "Connection to Event Hubs failed, will attempt connection again.",
+        :error_message => e.getMessage(),
+        :class => e.class.name,
+        :retry_in_seconds => retry_interval
+      )
+
+      # Wait for interval
+      sleep(retry_interval)
+      
+      # Add attempt and retry
+      try += 1
+      retry
+    end
+
+    # Pass event to sender on encode 
+    @codec.on_event(&method(:send_record))
+  end # def register
+
+  public
+  def close
+    @eventhub_client.closeSync();
+    @executor_service.shutdown();
+  end # def close
+  
+  public
+  def receive(event)
+    begin
+      @codec.encode(event)
+    rescue => e
+      @logger.warn("Error encoding event", :exception => e, :event => event)
+    end
+  end # def receive
+
+  private
+  def send_record(event, payload)
+    begin
+      # Create EventData object and convert payload to bytes
+      eh_event = EventData.create(ByteBuffer::wrap(payload.to_java_bytes))
+      
+      # Add property bag
+      if (!@properties_bag.nil?)
+        @properties_bag.each do |key, value|
+          eh_event.getProperties().put(event.sprintf(key).to_java_string, event.sprintf(value).to_java_string)
+        end
+      end
+
+      # Send using client
+      @eventhub_client.sendSync(eh_event)
+    rescue => e
+      @logger.warn("Error sending event", :exception => e, :event => event)
+    end
+  end # def send_record
+end # class LogStash::Outputs::AzureEventHubs

data/logstash-output-azure_event_hubs.gemspec

@@ -0,0 +1,37 @@
+GEM_VERSION = File.read(File.expand_path(File.join(File.dirname(__FILE__), "VERSION"))).strip unless defined?(GEM_VERSION)
+
+Gem::Specification.new do |s|
+  s.name          = 'logstash-output-azure_event_hubs'
+  s.version       = GEM_VERSION
+  s.licenses      = ['Apache-2.0']
+  s.summary       = 'Writes events to Azure Event Hubs'
+  s.description   = 'This is a Logstash output plugin used to write events to an Azure Event Hub'
+  s.homepage      = 'https://github.com/bryanklewis/logstash-output-azure_event_hubs'
+  s.authors       = ['Bryan Lewis']
+  s.email         = 'dbre@micron.com'
+  s.require_paths = ['lib', 'vendor/jar-dependencies']
+
+  # Files
+  s.files = Dir['lib/**/*', 'spec/**/*', 'vendor/jar-dependencies/**/*.jar', 'vendor/jar-dependencies/**/*.rb', '*.gemspec', '*.md', 'CONTRIBUTORS', 'Gemfile', 'LICENSE', 'VERSION', 'NOTICE']
+
+  # Tests
+  s.test_files = s.files.grep(%r{^(test|spec|features)/})
+
+  # Metadata "logstash_* => .." are special flags to indicate this a logstash plugin
+  s.metadata = {
+    "logstash_plugin" => "true",
+    "logstash_group" => "output",
+    "source_code_uri" => "https://github.com/bryanklewis/logstash-output-azure_event_hubs",
+    "allowed_push_host" => "https://rubygems.org"
+  }
+
+  # Gem dependencies
+  s.add_runtime_dependency "logstash-core-plugin-api", "~> 2.0"
+  s.add_runtime_dependency 'logstash-codec-plain'
+  s.add_runtime_dependency 'logstash-codec-json'
+
+  s.add_development_dependency 'logstash-devutils'
+
+  # Jar dependencies
+  s.add_development_dependency 'jar-dependencies'
+end

data/spec/outputs/azure_event_hubs_spec.rb

@@ -0,0 +1,22 @@
+# encoding: utf-8
+require "logstash/devutils/rspec/spec_helper"
+require "logstash/outputs/azure_event_hubs"
+require "logstash/codecs/plain"
+require "logstash/event"
+
+describe LogStash::Outputs::AzureEventHubs do
+  let(:sample_event) { LogStash::Event.new }
+  let(:output) { LogStash::Outputs::AzureEventHubs.new }
+
+  before do
+    output.register
+  end
+
+  describe "receive message" do
+    subject { output.receive(sample_event) }
+
+    it "returns a string" do
+      expect(subject).to eq("Event received")
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: logstash-output-azure_event_hubs
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bryan Lewis
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2019-06-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  name: logstash-core-plugin-api
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: logstash-codec-plain
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: logstash-codec-json
+  prerelease: false
+  type: :runtime
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: logstash-devutils
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  name: jar-dependencies
+  prerelease: false
+  type: :development
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: This is a Logstash output plugin used to write events to an Azure Event
+  Hub
+email: dbre@micron.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTORS
+- Gemfile
+- LICENSE
+- NOTICE
+- README.md
+- VERSION
+- lib/logstash-output-azure_event_hubs_jars.rb
+- lib/logstash/outputs/azure_event_hubs.rb
+- logstash-output-azure_event_hubs.gemspec
+- spec/outputs/azure_event_hubs_spec.rb
+homepage: https://github.com/bryanklewis/logstash-output-azure_event_hubs
+licenses:
+- Apache-2.0
+metadata:
+  logstash_plugin: 'true'
+  logstash_group: output
+  source_code_uri: https://github.com/bryanklewis/logstash-output-azure_event_hubs
+  allowed_push_host: https://rubygems.org
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+- vendor/jar-dependencies
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project:
+rubygems_version: 2.7.6
+signing_key:
+specification_version: 4
+summary: Writes events to Azure Event Hubs
+test_files:
+- spec/outputs/azure_event_hubs_spec.rb