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