2 Star 2 Fork 2

SkyWalking / skywalking-nginx-lua

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README
Apache-2.0

Apache SkyWalking Nginx Agent

Sky Walking logo

Twitter Follow

CI

SkyWalking Nginx Agent provides the native tracing capability for Nginx powered by Nginx LUA module.

This agent follows the SkyWalking tracing and header protocol. It reports tracing data to SkyWalking APM through HTTP protocol. All HTTP 1.1 requests go through Nginx could be collected by this agent.

Setup Doc

The following setup is targeting for OpenResty, if you want SkyWalking integrated Gateway, you could jump to

  1. APISIX documentation.
  2. Kong plugin documentation.
http {
    lua_package_path "/Path/to/.../skywalking-nginx-lua/lib/?.lua;;";

    # Buffer represents the register inform and the queue of the finished segment
    lua_shared_dict tracing_buffer 100m;

    # Init is the timer setter and keeper
    # Setup an infinite loop timer to do register and trace report.
    init_worker_by_lua_block {
        local metadata_buffer = ngx.shared.tracing_buffer

        -- Set service name
        metadata_buffer:set('serviceName', 'User Service Name')
        -- Instance means the number of Nginx deployment, does not mean the worker instances
        metadata_buffer:set('serviceInstanceName', 'User Service Instance Name')
        -- type 'boolean', mark the entrySpan include host/domain
        metadata_buffer:set('includeHostInEntrySpan', false)
        -- set ignoreSuffix, If the operation name(HTTP URI) of the entry span includes suffixes in this set, this segment would be ignored. Multiple values should be separated by a comma(',').
        -- require("skywalking.util").set_ignore_suffix(".jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.svg")

        -- set random seed
        require("skywalking.util").set_randomseed()
        require("skywalking.client"):startBackendTimer("http://127.0.0.1:8080")

        -- If there is a bug of this `tablepool` implementation, we can
        -- disable it in this way
        -- require("skywalking.util").disable_tablepool()

        skywalking_tracer = require("skywalking.tracer")
    }

    server {
        listen 8090;
        
        location /ingress {
            default_type text/html;

            rewrite_by_lua_block {
                ------------------------------------------------------
                -- NOTICE, this should be changed manually
                -- This variable represents the upstream logic address
                -- Please set them as service logic name or DNS name
                --
                -- Currently, we can not have the upstream real network address
                ------------------------------------------------------
                skywalking_tracer:start("upstream service")
                -- If you want correlation custom data to the downstream service
                -- skywalking_tracer:start("upstream service", {custom = "custom_value"})
            }

            -- Target upstream service
            proxy_pass http://127.0.0.1:8080/backend;

            body_filter_by_lua_block {
                if ngx.arg[2] then
                    skywalking_tracer:finish()
                end
            }

            log_by_lua_block {
                skywalking_tracer:prepareForReport()
            }
        }
    }
}

Download

Please head to the releases page to download a release of Apache SkyWalking.

Require SkyWalking 8 OAP server

Set up dev env

Debug Startup

By using the /examples/nginx.conf, you could start the Nginx with LUA module or OpenResty. Such as nginx -c /path/to/skywalking-nginx-lua/examples/nginx.conf Then you could

  1. See the instance properties update logs happens on the console log.
2020/04/04 15:15:37 [debug] 12089#1446111: *4 [lua] content_by_lua(nginx.conf:175):4: Instance report request = {"service":"User Service Name","serviceInstance":"User Service Instance Name","properties":[{"language":"Lua"}]}
2020/04/04 15:15:37 [debug] 12089#1446111: *2 [lua] client.lua:89: reportServiceInstance(): Instance report response = {}
  1. See the heartbeat logs happens after the register logs
2020/04/04 15:15:40 [debug] 12089#1446111: *4 [lua] content_by_lua(nginx.conf:188):3: KeepAlive request = {"service":"User Service Name","serviceInstance":"User Service Instance Name"}
  1. Access the http://127.0.0.1:8080/ingress then you could see the tracing happens and reported spans in the logs.
2020/04/04 15:15:46 [debug] 12089#1446111: *11 [lua] tracer.lua:83: prepareForReport(): segment = {"traceId":"1585984546953.410917649.45972","serviceInstance":"User Service Instance Name","spans":[{"operationName":"\/tier2\/lb","startTime":1585984546967,"endTime":1585984546968,"spanType":"Exit","spanId":1,"isError":false,"parentSpanId":0,"componentId":6000,"peer":"backend service","spanLayer":"Http"},{"operationName":"\/tier2\/lb","startTime":1585984546967,"tags":[{"key":"http.method","value":"GET"},{"key":"http.params","value":"http:\/\/127.0.0.1\/tier2\/lb"}],"endTime":1585984546968,"spanType":"Entry","spanId":0,"isError":false,"parentSpanId":-1,"componentId":6000,"refs":[{"traceId":"1585984546953.410917649.45972","networkAddressUsedAtPeer":"upstream service","parentEndpoint":"\/ingress","parentServiceInstance":"User Service Instance Name","parentSpanId":1,"parentService":"User Service Name","parentTraceSegmentId":"1585984546953.410917649.45972","refType":"CrossProcess"}],"spanLayer":"Http"}],"service":"User Service Name","traceSegmentId":"1585984546967.449397702.9959"}
2020/04/04 15:15:46 [debug] 12089#1446111: *11 [lua] tracer.lua:87: prepareForReport(): segment buffer size = 1
2020/04/04 15:15:46 [debug] 12089#1446111: *8 [lua] tracer.lua:83: prepareForReport(): segment = {"traceId":"1585984546953.410917649.45972","serviceInstance":"User Service Instance Name","spans":[{"operationName":"\/ingress","startTime":1585984546953,"endTime":1585984546968,"spanType":"Exit","spanId":1,"isError":false,"parentSpanId":0,"componentId":6000,"peer":"upstream service","spanLayer":"Http"},{"operationName":"\/ingress","startTime":1585984546953,"tags":[{"key":"http.method","value":"GET"},{"key":"http.params","value":"http:\/\/localhost\/ingress"}],"endTime":1585984546968,"spanType":"Entry","spanId":0,"parentSpanId":-1,"isError":false,"spanLayer":"Http","componentId":6000}],"service":"User Service Name","traceSegmentId":"1585984546953.410917649.45972"}

Local Development and Unit Tests

All codes in the lib/skywalking require the *_test.lua to do the UnitTest. To run that, you need to install

  • Lua 5.1
  • LuaRocks

The following libs are required in runtime or test cases, please use LuaRocks to install them.

APIs

This LUA tracing lib is originally designed for Nginx+LUA/OpenResty ecosystems. But we write it to support more complex cases. If you just use this in the Ngnix, Setup Doc should be good enough. The following APIs are for developers or using this lib out of the Nginx case.

Nginx APIs

  • startTimer, require("skywalking.client"):startBackendTimer("http://127.0.0.1:8080"). Start the backend timer. This timer register the metadata and report traces to the backend.
  • destroyBackendTimer, require("skywalking.client"):destroyBackendTimer(). Stop the timer created by startBackendTimer, and clean unreported data.
  • start, require("skywalking.tracer"):start("upstream service", correlation). Begin the tracing before the upstream beginning. The custom data (table type) can be injected as the second parameter, and then they will be propagated to the downstream service. If upstream service could be determined precisely later, keep it as nil and call inject method when peer(upstream address) is resolved by load balancer and DNS resolver.
  • inject, require("skywalking.tracer"):inject(exitSpan, peer, correlation). Inject an exit span context and correlation context into carrier, and then they will be propagated to the downstream service. (Since v1.0, advanced API, called when you update the peer of exit span.)
  • finish, require("skywalking.tracer"):finish(). Finish the tracing for this HTTP request.
  • prepareForReport, require("skywalking.tracer"):prepareForReport(). Prepare the finished segment for further report.

Tracing APIs at LUA level

TracingContext is the entrance API for lua level tracing.

  • TracingContext.new(serviceId, serviceInstID), create an active tracing context.
  • TracingContext.newNoOP(), create a no OP tracing context.
  • TracingContext.drainAfterFinished(), fetch the segment includes all finished spans.
  • TracingContext.inject(exitSpan, peer, correlation), inject an exit span context and correlation context into carrier, and then they will be propagated to the downstream service by outgoing HTTP request. (Since v1.0, advanced API, called when you update the peer of exit span.)

Create 2 kinds of span

  • TracingContext.createEntrySpan(operationName, parent, contextCarrier)
  • TracingContext.createExitSpan(operationName, parent, peer, contextCarrier)

Create 2 kinds of span API v1

  • TracingContext.createEntrySpan(operationName, parent, contextCarrier)
  • TracingContext.createExitSpan(operationName, parent)

Contact Us

  • Submit an issue with [NIGNX-LUA] as the issue title prefix.
  • Mail list: dev@skywalking.apache.org. Mail to dev-subscribe@skywalking.apache.org, follow the reply to subscribe the mail list.
  • Join skywalking channel at Apache Slack. If the link is not working, find the latest one at Apache INFRA WIKI.
  • QQ Group: 392443393(2000/2000, not available), 901167865(available)

Release Guide

All committers should follow Release Guide to publish the official release.

License

Apache 2.0

# Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file # distributed with this work for additional information # regarding copyright ownership. The ASF licenses this file # to you 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. header: license: spdx-id: Apache-2.0 copyright-owner: Apache Software Foundation paths-ignore: - 'dist' - 'licenses' - '**/*.md' - 'LICENSE' - 'NOTICE' - 'rockspec' - '.gitignore' - '.luacheckrc' - '.mvn' - 'lib/resty' - 'lib/skywalking/dependencies' comment: on-failure

简介

The Nginx Lua agent for Apache SkyWalking 展开 收起
Apache-2.0
取消

发行版

暂无发行版

贡献者

全部

近期动态

加载更多
不能加载更多了
Lua
1
https://gitee.com/OpenSkywalking/skywalking-nginx-lua.git
git@gitee.com:OpenSkywalking/skywalking-nginx-lua.git
OpenSkywalking
skywalking-nginx-lua
skywalking-nginx-lua
master

搜索帮助