« 基本配置 集成 »
Elastic 文档 ›Elasticsearch Ruby 客户端 [8.14] ›配置

高级配置

编辑

高级配置编辑

客户端支持许多配置选项，用于设置和管理连接、配置日志记录、自定义传输库等。

设置主机编辑

要连接到特定的 Elasticsearch 主机

Elasticsearch::Client.new(host: 'search.myserver.com')

要连接到具有特定端口的主机

Elasticsearch::Client.new(host: 'myhost:8080')

要连接到多个主机

Elasticsearch::Client.new(hosts: ['myhost1', 'myhost2'])

您可以传递主机信息的哈希数组，而不是字符串

Elasticsearch::Client.new(hosts: [ { host: 'myhost1', port: 8080 }, { host: 'myhost2', port: 8080 } ])

指定多个主机时，您可能希望启用 retry_on_failure 或 retry_on_status 选项，以便在另一个节点上执行失败的请求（请参阅故障重试）。

常见的 URL 部分（方案、HTTP 身份验证凭据、URL 前缀等）会自动处理

Elasticsearch::Client.new(url: 'https://username:[email protected]:4430/search')

您可以传递多个以逗号分隔的 URL

Elasticsearch::Client.new(urls: 'https://127.0.0.1:9200,https://127.0.0.1:9201')

配置 URL 的另一种方法是导出 ELASTICSEARCH_URL 变量。

客户端将自动在主机之间使用循环算法（除非您选择或实现了不同的连接选择器）。

默认端口编辑

默认端口为 9200。如果您的主机端口与此默认端口不同，请指定一个端口。

如果您使用的是 Elastic Cloud，则默认端口为 9243 端口。您必须单独提供用户名和密码，以及可选的端口。请参阅Elastic Cloud。

日志记录编辑

要使用默认记录器（Ruby 的 ::Logger 类的实例）将请求和响应记录到标准输出，请将 log 参数设置为 true

Elasticsearch::Client.new(log: true)

您还可以使用ecs-logging，这是一组库，使您能够将应用程序日志转换为符合Elastic Common Schema的结构化日志。请参阅Elastic Common Schema (ECS)。

要在 Curl 格式中跟踪请求和响应，请设置 trace 参数

Elasticsearch::Client.new(trace: true)

您可以自定义默认记录器或跟踪器

client.transport.logger.formatter = proc { |s, d, p, m| "#{s}: #{m}\n" }
client.transport.logger.level = Logger::INFO

或者，您可以使用自定义的 ::Logger 实例

Elasticsearch::Client.new(logger: Logger.new(STDERR))

您可以将任何符合要求的记录器实现传递给客户端

require 'logging' # https://github.com/TwP/logging/

log = Logging.logger['elasticsearch']
log.add_appenders Logging.appenders.stdout
log.level = :info

client = Elasticsearch::Client.new(logger: log)

APM 集成编辑

此客户端通过 Elastic APM 代理与 Elastic APM 无缝集成。如果您在代码中使用代理，它会自动捕获客户端请求。如果您使用的是 elastic-apm v3.8.0 或更高版本，则可以在 config/elastic_apm.yml 中将 capture_elasticsearch_queries 设置为 true，以从 Elasticsearch 中的请求中捕获正文。请参阅此示例。

自定义 HTTP 标头编辑

您可以在客户端的初始化程序上设置自定义 HTTP 标头

client = Elasticsearch::Client.new(
  transport_options: {
    headers:
      {user_agent: "My App"}
  }
)

您还可以将 headers 作为参数传递给任何 API 端点，以为请求设置自定义标头

client.search(index: 'myindex', q: 'title:test', headers: {user_agent: "My App"})

使用 X-Opaque-Id 识别正在运行的任务编辑

X-Opaque-Id 标头允许跟踪某些调用，或将某些任务与启动它们的客户端相关联（请参阅文档）。要使用此功能，您需要在每个请求的客户端上为 opaque_id 设置一个 ID。示例

client = Elasticsearch::Client.new
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')

搜索请求包含以下 HTTP 标头

X-Opaque-Id: 123456

您还可以在初始化客户端时为 X-Opaque-Id 设置前缀。如果您使用的是 X-Opaque-Id，这将添加到您在每个请求之前设置的 ID 之前。示例

client = Elasticsearch::Client.new(opaque_id_prefix: 'eu-west1_')
client.search(index: 'myindex', q: 'title:test', opaque_id: '123456')

请求包含以下 HTTP 标头

X-Opaque-Id: eu-west1_123456

设置超时编辑

对于 Elasticsearch 中的许多操作，HTTP 库的默认超时时间太短。要增加超时时间，可以使用 request_timeout 参数

Elasticsearch::Client.new(request_timeout: 5*60)

您还可以使用下面记录的 transport_options 参数。

随机化主机编辑

如果将多个主机传递给客户端，默认情况下，它会以循环方式在这些主机之间轮换。当同一个客户端在多个进程中运行时（例如，在像 Thin 这样的 Ruby Web 服务器中），它可能会“同时”保持连接到相同的节点。为了防止这种情况，您可以在初始化和重新加载时随机化主机集合

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], randomize_hosts: true)

故障重试编辑

当客户端使用多个主机初始化时，在不同的主机上重试失败的请求是有意义的

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], retry_on_failure: true)

默认情况下，客户端不会重试请求。您可以通过将一个数字传递给 retry_on_failure 来指定在引发异常之前重试的次数

 Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], retry_on_failure: 5)

您还可以使用 retry_on_status 在返回特定状态代码时重试

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], retry_on_status: [502, 503])

这两个参数也可以一起使用

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], retry_on_status: [502, 503], retry_on_failure: 10)

您还可以设置以毫秒为单位的 delay_on_retry 值。这将在重试之间添加延迟等待时间

 Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], retry_on_failure: 5, delay_on_retry: 1000)

重新加载主机编辑

默认情况下，Elasticsearch 会动态发现集群中的新节点。您可以在客户端中利用这一点，并定期检查新节点以分散负载。

要在每 10,000 个请求上检索和使用节点信息 API中的信息

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], reload_connections: true)

您可以传递一个特定的请求数量，在该数量之后应执行重新加载

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], reload_connections: 1_000)

要在失败时重新加载连接，请使用

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], reload_on_failure: true)

重新加载超时时间，如果默认情况下在 1 秒内未完成。要更改设置

Elasticsearch::Client.new(hosts: ['localhost:9200', 'localhost:9201'], sniffer_timeout: 3)

将重新加载主机（“嗅探”）与身份验证一起使用时，请将方案、用户和密码与主机信息一起传递 - 或者，为了更清晰起见，在 http 选项中传递

Elasticsearch::Client.new(
  host: 'localhost:9200',
  http: { scheme: 'https', user: 'U', password: 'P' },
  reload_connections: true,
  reload_on_failure: true
)

连接选择器编辑

默认情况下，客户端使用 Elastic::Transport::Transport::Connections::Selector::RoundRobin 策略以循环方式轮换连接。

您可以实现自己的策略来自定义行为。例如，让我们采用“感知机架”的策略，该策略优先选择具有特定属性的节点。仅当这些节点不可用时，该策略才会使用其他节点

class RackIdSelector
  include Elastic::Transport::Transport::Connections::Selector::Base

  def select(options={})
    connections.select do |c|
      # Try selecting the nodes with a `rack_id:x1` attribute first
      c.host[:attributes] && c.host[:attributes][:rack_id] == 'x1'
    end.sample || connections.to_a.sample
  end
end

Elasticsearch::Client.new hosts: ['x1.search.org', 'x2.search.org'], selector_class: RackIdSelector

序列化器实现编辑

默认情况下，MultiJSON 库用作序列化器实现，它根据可用的 gem 选择“正确”的适配器。

但是，序列化组件是可插拔的，因此您可以通过包含 Elastic::Transport::Transport::Serializer::Base 模块、实现所需的协定并将其实现作为 serializer_class 或 serializer 参数传递给客户端来编写自己的序列化器。

异常处理编辑

该库为各种客户端和服务器错误以及不成功的 HTTP 响应定义了许多异常类，从而可以以所需的粒度处理特定异常。

最高级别的异常是 Elastic::Transport::Transport::Error，它针对任何通用的客户端或服务器错误引发。

Elastic::Transport::Transport::ServerError 仅针对服务器错误引发。

作为特定于响应的错误的示例，404 响应状态会引发 Elastic::Transport::Transport::Errors::NotFound 异常。

最后，当连接重新加载（“嗅探”）超时时，会引发 Elastic::Transport::Transport::SnifferTimeoutError。

« 基本配置 集成 »