本地转发器(预览版)Local forwarder (Preview)

本地转发器是从各种框架中收集 Application Insights 或 OpenCensus 遥测数据并将其路由到 Application Insights 的代理。Local forwarder is an agent that collects Application Insights or OpenCensus telemetry from a variety of SDKs and routes it to Application Insights. 它能够在 Windows 和 Linux 下运行。It's capable of running under Windows and Linux. 也可以在 macOS 下运行,但目前并不正式支持这种运行方式。You may also be able to run it under macOS, but that is not officially supported at this time.

运行本地转发器Running local forwarder

本地转发器是 GitHub 上的一个开源项目Local forwarder is an open source project on GitHub. 可通过多种方式在多个平台上运行本地转发器。There are a variety of ways to run local forwarder on multiple platforms.

WindowsWindows

Windows 服务Windows Service

在 Windows 中运行本地转发器的最简单方法就是将其作为 Windows 服务安装。The easiest way of running local forwarder under Windows is by installing it as a Windows Service. 服务版本随附了一个 Windows 服务可执行文件 (WindowsServiceHost/Microsoft.LocalForwarder.WindowsServiceHost.exe),可轻松将其注册到操作系统中。The release comes with a Windows Service executable (WindowsServiceHost/Microsoft.LocalForwarder.WindowsServiceHost.exe) which can be easily registered with the operating system.

备注

本地转发器服务需要 .NET Framework 4.7 或更高版本。The local forwarder service requires a minimum of .NET Framework 4.7. 如果未安装 .NET Framework 4.7,则该服务可完成安装,但不会启动。If you do not have .NET Framework 4.7 the service will install, but it won't start. 若要获取最新版本的 .NET framework, 请访问 .NET Framework 下载页To access the lastest version of the .NET Framework visit the .NET Framework download page.

  1. 从 GitHub 上的本地转发器发布页下载 LF.WindowsServiceHost.zip 文件。Download the LF.WindowsServiceHost.zip file from the local forwarder release page on GitHub.

    本地转发器发布下载页的屏幕截图

  2. 在这个易于演示的示例中,我们只需将该 .zip 文件解压缩到路径 C:\LF-WindowsServiceHostIn this example for ease of demonstration, we will just extract the .zip file to the path C:\LF-WindowsServiceHost.

    若要注册该服务并将其配置为在系统引导时启动,请以管理员身份在命令行中运行以下命令:To register the service and configure it to start at system boot run the following from the command line as Administrator:

    sc create "Local Forwarder" binpath="C:\LF-WindowsServiceHost\Microsoft.LocalForwarder.WindowsServiceHost.exe" start=auto
    

    应会收到以下响应:You should receive a response of:

    [SC] CreateService SUCCESS

    若要通过服务 GUI 检查新服务,请键入 services.mscTo examine your new service via the Services GUI type services.msc

    本地转发器服务的屏幕截图

  3. 右键单击新的本地转发器并选择“启动”。 Right-click the new local forwarder and select Start. 现在,该服务将进入运行状态。Your service will now enter a running state.

  4. 默认情况下,创建的服务不提供任何恢复操作。By default the service is created without any recovery actions. 可以单击右键,并选择“属性” > “恢复”来配置发生服务故障时的自动响应方式。 You can right-click and select Properties > Recovery to configure automatic responses to a service failure.

    或者,如果你偏向于以编程方式设置发生故障时的自动恢复选项,可以使用:Or if you prefer to set automatic recovery options programmatically for when failures occur, you can use:

    sc failure "Local Forwarder" reset= 432000 actions= restart/1000/restart/1000/restart/1000
    
  5. Microsoft.LocalForwarder.WindowsServiceHost.exe 文件所在的同一位置(在本示例中为 C:\LF-WindowsServiceHost),有一个名为 LocalForwarder.config 的文件。In the same location as your Microsoft.LocalForwarder.WindowsServiceHost.exe file, which in this example is C:\LF-WindowsServiceHost there is a file called LocalForwarder.config. 这是一个基于 XML 的文件,可用于调整本地转发器的配置,并指定分布式跟踪数据要转发到的 Application Insights 资源的检测密钥。This is an xml based file that allows you to adjust the configuration of your localforwader and specify the instrumentation key of the Application Insights resource you want your distributed tracing data forwarded.

    通过编辑 LocalForwarder.config 文件添加检测密钥后,请务必重启“本地转发器服务”,使更改生效。 After editing the LocalForwarder.config file to add your instrumentation key, be sure to restart the Local Forwarder Service to allow your changes to take effect.

  6. 若要确认所需的设置是否已准备就绪并且本地转发器正在按预期侦听跟踪数据,请检查 LocalForwarder.log 文件。To confirm that your desired settings are in place and that the local forwarder is listening for trace data as expected check the LocalForwarder.log file. 在该文件的底部,应会看到下图所示的结果:You should see results similar to the image below at the bottom of the file:

    LocalForwarder.log 文件的屏幕截图

控制台应用程序Console application

对于某些用例,以控制台应用程序的形式运行本地转发器可能更有利。For certain use cases, it might be beneficial to run local forwarder as a console application. 服务版本随附了控制台主机的以下可执行文件版本:The release comes with the following executable versions of the console host:

  • 框架相关的 .NET Core 二进制文件 /ConsoleHost/publish/Microsoft.LocalForwarder.ConsoleHost.dlla framework-dependent .NET Core binary /ConsoleHost/publish/Microsoft.LocalForwarder.ConsoleHost.dll. 运行此二进制文件需要安装 .NET Core 运行时;请参阅此下载了解详细信息。Running this binary requires a .NET Core runtime to be installed; refer to this download page for details.
    E:\uncdrop\ConsoleHost\publish>dotnet Microsoft.LocalForwarder.ConsoleHost.dll
    
  • 适用于 x86 和 x64 平台的独立 .NET Core 二进制文件集。a self-contained .NET Core set of binaries for x86 and x64 platforms. 不需要 .NET Core 运行时即可运行这些二进制文件。These don't require .NET Core runtime to run. /ConsoleHost/win-x86/publish/Microsoft.LocalForwarder.ConsoleHost.exe/ConsoleHost/win-x64/publish/Microsoft.LocalForwarder.ConsoleHost.exe/ConsoleHost/win-x86/publish/Microsoft.LocalForwarder.ConsoleHost.exe, /ConsoleHost/win-x64/publish/Microsoft.LocalForwarder.ConsoleHost.exe.
    E:\uncdrop\ConsoleHost\win-x86\publish>Microsoft.LocalForwarder.ConsoleHost.exe
    E:\uncdrop\ConsoleHost\win-x64\publish>Microsoft.LocalForwarder.ConsoleHost.exe
    

LinuxLinux

与在 Windows 中一样,服务版本随附了控制台主机的以下可执行文件版本:As with Windows, the release comes with the following executable versions of the console host:

  • 框架相关的 .NET Core 二进制文件 /ConsoleHost/publish/Microsoft.LocalForwarder.ConsoleHost.dlla framework-dependent .NET Core binary /ConsoleHost/publish/Microsoft.LocalForwarder.ConsoleHost.dll. 运行此二进制文件需要安装 .NET Core 运行时;请参阅此下载了解详细信息。Running this binary requires a .NET Core runtime to be installed; refer to this download page for details.
dotnet Microsoft.LocalForwarder.ConsoleHost.dll
  • 适用于 linux-64 的独立 .NET Core 二进制文件集。a self-contained .NET Core set of binaries for linux-64. 不需要 .NET Core 运行时即可运行此二进制文件。This one doesn't require .NET Core runtime to run. /ConsoleHost/linux-x64/publish/Microsoft.LocalForwarder.ConsoleHost/ConsoleHost/linux-x64/publish/Microsoft.LocalForwarder.ConsoleHost.
user@machine:~/ConsoleHost/linux-x64/publish$ sudo chmod +x Microsoft.LocalForwarder.ConsoleHost
user@machine:~/ConsoleHost/linux-x64/publish$ ./Microsoft.LocalForwarder.ConsoleHost

许多 Linux 用户希望将本地转发器作为守护程序运行。Many Linux users will want to run local forwarder as a daemon. Linux 系统随附了多种服务管理解决方案,例如 Upstart、sysv 或 systemd。Linux systems come with a variety of solutions for service management, like Upstart, sysv, or systemd. 可以使用任何解决方案版本以最适合方案的方式运行本地转发器。Whatever your particular version is, you can use it to run local forwarder in a way that is most appropriate for your scenario.

例如,让我们使用 systemd 创建一个守护程序服务。As an example, let's create a daemon service using systemd. 我们将使用框架相关的版本,但使用独立的二进制文件也可以实现相同的效果。We'll use the framework-dependent version, but the same can be done for a self-contained one as well.

  • 创建以下名为 localforwarder.service 的服务文件,并将其置于 /lib/systemd/system 中。create the following service file named localforwarder.service and place it into /lib/systemd/system. 本示例假设用户名为 SAMPLE_USER,并且已将本地转发器框架相关的二进制文件从 ConsoleHost/publish 复制到 /home/SAMPLE_USER/LOCALFORWARDER_DIRThis sample assumes your user name is SAMPLE_USER and you've copied local forwarder framework-dependent binaries (from /ConsoleHost/publish) to /home/SAMPLE_USER/LOCALFORWARDER_DIR.
# localforwarder.service
# Place this file into /lib/systemd/system/
# Use 'systemctl enable localforwarder' to start the service automatically on each boot
# Use 'systemctl start localforwarder' to start the service immediately

[Unit]
Description=Local Forwarder service
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=SAMPLE_USER
WorkingDirectory=/home/SAMPLE_USER/LOCALFORWARDER_DIR
ExecStart=/usr/bin/env dotnet /home/SAMPLE_USER/LOCALFORWARDER_DIR/Microsoft.LocalForwarder.ConsoleHost.dll noninteractive

[Install]
WantedBy=multi-user.target
  • 运行以下命令,指示 systemd 在每次引导时都要启动本地转发器Run the following command to instruct systemd to start local forwarder on every boot
systemctl enable localforwarder
  • 运行以下命令,指示 systemd 立即启动本地转发器Run the following command to instruct systemd to start local forwarder immediately
systemctl start localforwarder
  • 通过检查 /home/SAMPLE_USER/LOCALFORWARDER_DIR 目录中的 * .log 文件来监视服务。Monitor the service by inspecting *.log files in the /home/SAMPLE_USER/LOCALFORWARDER_DIR directory.

MacMac

本地转发器可在 macOS 中工作,但目前不受正式支持。Local forwarder may work with macOS, but it is currently not officially supported.

自托管Self-hosting

本地转发器还作为 .NET Standard NuGet 包分发,可将它托管在你自己的 .NET 应用程序中。Local forwarder is also distributed as a .NET Standard NuGet package, allowing you to host it inside your own .NET application.

using Library;
...
Host host = new Host();

// see section below on configuring local forwarder
string configuration = ...;
    
host.Run(config, TimeSpan.FromSeconds(5));
...
host.Stop();

配置本地转发器Configuring local forwarder

  • 运行本地转发器的某个自有主机(控制台主机或 Windows 服务主机)时,你会发现二进制文件旁边有一个 LocalForwarder.configWhen running one of local forwarder's own hosts (Console Host or Windows Service Host), you will find LocalForwarder.config placed next to the binary.
  • 自我托管本地转发器 NuGet 时,必须在代码中提供相同格式的配置(请参阅有关自我托管的部分)。When self-hosting the local forwarder NuGet, the configuration of the same format must be provided in code (see section on self-hosting). 有关配置语法,请查看 GitHub 存储库中的 LocalForwarder.configFor the configuration syntax, check the LocalForwarder.config in the GitHub repository.

备注

不同发行版的配置可能会有变化,请留意所用的版本。Configuration may change from release to release, so pay attention to which version you're using.

监视本地转发器Monitoring local forwarder

跟踪将写出到文件系统中运行本地转发器的可执行文件的旁边(查看 * .log 文件)。Traces are written out to the file system next to the executable that runs local forwarder (look for *.log files). 可在该可执行文件的旁边添加一个名为 NLog.config 的文件,以提供自己的配置来取代默认配置。You can place a file with a name of NLog.config next to the executable to provide your own configuration in place of the default one. 有关格式说明,请参阅文档See documentation for the description of the format.

如果未提供配置文件(默认设置),则本地转发器将使用位于此处的默认配置。If no configuration file is provided (which is the default), Local forwarder will use the default configuration, which can be found here.

后续步骤Next steps