README.md in elasticsearch-transport-7.6.0 vs README.md in elasticsearch-transport-7.7.0.pre

- old
+ new

@@ -35,11 +35,11 @@ Currently these libraries will be automatically detected and used: - [Patron](https://github.com/toland/patron) - [HTTPClient](https://rubygems.org/gems/httpclient) - [Net::HTTP::Persistent](https://rubygems.org/gems/net-http-persistent) -**Note on [Typhoeus](https://github.com/typhoeus/typhoeus)**: Typhoeus is compatible and will be automatically detected too. However, the latest release (v1.3.1 at the moment of writing this) is not compatible with Faraday 1.0. [It still uses the deprecated `Faraday::Error` namespace](https://github.com/typhoeus/typhoeus/blob/v1.3.1/lib/typhoeus/adapters/faraday.rb#L100). If you want to use it with this gem, we suggest getting `master` from GitHub, since this has been fixed for v1.4.0. We'll update this if/when v1.4.0 is released. +**Note on [Typhoeus](https://github.com/typhoeus/typhoeus)**: Typhoeus is compatible and will be automatically detected too. However, the latest release (v1.3.1 at the moment of writing this) is not compatible with Faraday 1.0. [It still uses the deprecated `Faraday::Error` namespace](https://github.com/typhoeus/typhoeus/blob/v1.3.1/lib/typhoeus/adapters/faraday.rb#L100). If you want to use it with this gem, we suggest getting `master` from GitHub, since this has been fixed for v1.4.0. We'll update this if/when v1.4.0 is released.a For detailed information, see example configurations [below](#transport-implementations). ## Installation @@ -76,10 +76,11 @@ * [Setting Hosts](#setting-hosts) * [Default port](#default-port) * [Connect using an Elastic Cloud ID](#connect-using-an-elastic-cloud-id) * [Authentication](#authentication) * [Logging](#logging) +* [Custom HTTP Headers](#custom-http-headers) * [Identifying running tasks with X-Opaque-Id](#identifying-running-tasks-with-x-opaque-id) * [Setting Timeouts](#setting-timeouts) * [Randomizing Hosts](#randomizing-hosts) * [Retrying on Failures](#retrying-on-failures) * [Reloading Hosts](#reloading-hosts) @@ -187,34 +188,65 @@ ### Logging To log requests and responses to standard output with the default logger (an instance of Ruby's {::Logger} class), set the `log` argument: - Elasticsearch::Client.new log: true +```ruby +Elasticsearch::Client.new log: true +``` + To trace requests and responses in the _Curl_ format, set the `trace` argument: - Elasticsearch::Client.new trace: true +```ruby +Elasticsearch::Client.new trace: true +``` You can customize the default logger or tracer: +```ruby client.transport.logger.formatter = proc { |s, d, p, m| "#{s}: #{m}\n" } client.transport.logger.level = Logger::INFO +``` Or, you can use a custom `::Logger` instance: - Elasticsearch::Client.new logger: Logger.new(STDERR) +```ruby +Elasticsearch::Client.new logger: Logger.new(STDERR) +``` You can pass the client any conforming logger implementation: - require 'logging' # https://github.com/TwP/logging/ +```ruby +require 'logging' # https://github.com/TwP/logging/ - log = Logging.logger['elasticsearch'] - log.add_appenders Logging.appenders.stdout - log.level = :info +log = Logging.logger['elasticsearch'] +log.add_appenders Logging.appenders.stdout +log.level = :info - client = Elasticsearch::Client.new logger: log +client = Elasticsearch::Client.new logger: log +``` + +### Custom HTTP Headers + +You can set a custom HTTP header on the client's initializer: + +```ruby +client = Elasticsearch::Client.new( + transport_options: { + headers: + {user_agent: "My App"} + } +) +``` + +You can also pass in `headers` as a parameter to any of the API Endpoints to set custom headers for the request: + +```ruby +client.search(index: 'myindex', q: 'title:test', headers: {user_agent: "My App"}) +``` + ### Identifying running tasks with X-Opaque-Id The X-Opaque-Id header allows to track certain calls, or associate certain tasks with the client that started them ([more on the Elasticsearch docs](https://www.elastic.co/guide/en/elasticsearch/reference/master/tasks.html#_identifying_running_tasks)). To use this feature, you need to set an id for `opaque_id` on the client on each request. Example: ```ruby @@ -328,28 +360,32 @@ It will auto-detect and use an _adapter_ for _Faraday_ based on gems loaded in your code, preferring HTTP clients with support for persistent connections. To use the [_Patron_](https://github.com/toland/patron) HTTP, for example, just require it: - require 'patron' +```ruby +require 'patron' +``` Then, create a new client, and the _Patron_ gem will be used as the "driver": - client = Elasticsearch::Client.new +```ruby +client = Elasticsearch::Client.new - client.transport.connections.first.connection.builder.adapter - # => Faraday::Adapter::Patron +client.transport.connections.first.connection.builder.adapter +# => Faraday::Adapter::Patron - 10.times do - client.nodes.stats(metric: 'http')['nodes'].values.each do |n| - puts "#{n['name']} : #{n['http']['total_opened']}" - end - end +10.times do + client.nodes.stats(metric: 'http')['nodes'].values.each do |n| + puts "#{n['name']} : #{n['http']['total_opened']}" + end +end - # => Stiletoo : 24 - # => Stiletoo : 24 - # => Stiletoo : 24 - # => ... +# => Stiletoo : 24 +# => Stiletoo : 24 +# => Stiletoo : 24 +# => ... +``` To use a specific adapter for _Faraday_, pass it as the `adapter` argument: client = Elasticsearch::Client.new adapter: :net_http_persistent