Add Util, TracingContext and Span APIs
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 4acdda5..5807ad9 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -52,5 +52,6 @@
- name: 'Run Tests'
run: |
cd lib/skywalking
- lua id_generator_test.lua
+ lua util_test.lua
+ lua span_test.lua
lua tracing_context_test.lua
\ No newline at end of file
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..9c8f3ea
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,201 @@
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "{}"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright {yyyy} {name of copyright owner}
+
+ Licensed 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.
\ No newline at end of file
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..e646f51
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,5 @@
+Apache SkyWalking
+Copyright 2017-2020 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
diff --git a/README.md b/README.md
index cb674c5..c9eedf1 100644
--- a/README.md
+++ b/README.md
@@ -14,6 +14,18 @@
# Setup Doc
TODO
+# APIs
+
+# Set up dev env
+All codes in the `lib/skywalking` require the `*_test.lua` to do the UnitTest. To run that, you need to install
+- Lua 5.3
+- LuaRocks
+
+The following libs are required in runtime or test cases, please use `LuaRocks` to install them.
+- luaunit
+- luasocket
+
+
# Download
Have no release yet.
diff --git a/lib/skywalking/span.lua b/lib/skywalking/span.lua
index e69de29..207be6e 100644
--- a/lib/skywalking/span.lua
+++ b/lib/skywalking/span.lua
@@ -0,0 +1,68 @@
+--
+-- 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.
+--
+
+local spanLayer = require("span_layer")
+local Context = require("tracing_context")
+local Util = require('util')
+
+Span = {
+ span_id,
+ parent_span_id,
+ operation_name,
+ tags,
+ logs,
+ layer = spanLayer.NONE,
+ isEntry = false,
+ isExit = false,
+ peer,
+ start_time,
+ end_time,
+ error_occurred = false,
+}
+
+-- Create an entry span, represent the HTTP incoming request.
+function Span:createEntrySpan(operationName, context, parent)
+ local span = self:new(operationName, context, parent)
+ span.isEntry = true
+
+ return span
+end
+
+-- Create a default span.
+-- Usually, this method wouldn't be called by outside directly.
+-- Read newEntrySpan, newExitSpan and newLocalSpan for more details
+function Span:new(operationName, context, parent)
+ local o = {}
+ setmetatable(o, self)
+ self.__index = self
+
+ o.operation_name = operationName
+ o.span_id = context.internal:nextSpanID()
+ if parent == nil then
+ -- As the root span, the parent span id is -1
+ o.parent_span_id = -1
+ else
+ o.parent_span_id = parent.span_id
+ end
+
+ context.internal:addActive(o)
+ o.start_time = Util.timestamp()
+
+ return o
+end
+
+return Span
diff --git a/lib/skywalking/id_generator.lua b/lib/skywalking/span_layer.lua
similarity index 75%
rename from lib/skywalking/id_generator.lua
rename to lib/skywalking/span_layer.lua
index 3054774..7cdec08 100644
--- a/lib/skywalking/id_generator.lua
+++ b/lib/skywalking/span_layer.lua
@@ -15,16 +15,13 @@
-- limitations under the License.
--
-socket=require'socket'
+Layer = {
+ NONE = {name = "NONE", value=0},
+ DB = {name = "DB", value=1},
+ RPC_FRAMEWORK = {name = "RPC_FRAMEWORK", value=2},
+ HTTP = {name = "HTTP", value=3},
+ MQ = {name = "MQ", value=4},
+ CACHE = {name = "CACHE", value=5},
+}
-IDGenerator = {}
-MAX_ID_PART2 = 1000000000
-MAX_ID_PART3 = 100000
-SEQ = 1
-
-function IDGenerator:newID()
- SEQ = SEQ + 1
- return {socket.gettime(), math.random( 0, MAX_ID_PART2), math.random( 0, MAX_ID_PART3) + SEQ}
-end
-
-return IDGenerator
\ No newline at end of file
+return Layer
\ No newline at end of file
diff --git a/lib/skywalking/span_test.lua b/lib/skywalking/span_test.lua
new file mode 100644
index 0000000..0523b63
--- /dev/null
+++ b/lib/skywalking/span_test.lua
@@ -0,0 +1,63 @@
+--
+-- 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.
+--
+
+local lu = require('luaunit')
+local TC = require('tracing_context')
+local Span = require('span')
+local SpanLayer = require("span_layer")
+
+TestSpan = {}
+ function TestSpan:testNewEntry()
+ local context = TC:new()
+ lu.assertNotNil(context)
+
+ local span1 = Span:createEntrySpan("operation_name", context, nil)
+ lu.assertNotNil(span1)
+ lu.assertEquals(span1.isEntry, true)
+ lu.assertEquals(span1.isExit, false)
+ lu.assertEquals(span1.layer, SpanLayer.NONE)
+
+ lu.assertEquals(#(context.internal.active_spans), 1)
+ end
+
+ function TestSpan:testNew()
+ local context = TC:new()
+ lu.assertNotNil(context)
+
+ local span1 = Span:new("operation_name", context, nil)
+ lu.assertNotNil(span1)
+ lu.assertEquals(span1.parent_span_id, -1)
+ lu.assertEquals(span1.span_id, 0)
+ lu.assertEquals(span1.operation_name, "operation_name")
+ local span2 = Span:new("operation_name", context, span1)
+ lu.assertEquals(span2.parent_span_id, 0)
+ lu.assertEquals(span2.span_id, 1)
+ lu.assertNotNil(span2.start_time)
+
+ -- Use new context to check again
+ context = TC:new()
+ lu.assertNotNil(context)
+
+ span1 = Span:new("operation_name", context, nil)
+ lu.assertNotNil(span1)
+ lu.assertEquals(span1.parent_span_id, -1)
+ lu.assertEquals(span1.span_id, 0)
+ end
+-- end TestSpan
+
+
+os.exit( lu.LuaUnit.run() )
\ No newline at end of file
diff --git a/lib/skywalking/tracing_context.lua b/lib/skywalking/tracing_context.lua
index fa42f9a..1e122e2 100644
--- a/lib/skywalking/tracing_context.lua
+++ b/lib/skywalking/tracing_context.lua
@@ -15,26 +15,69 @@
-- limitations under the License.
--
-local idGen = require('id_generator')
+local Util = require('util')
TracingContext = {
- span_id_seq = 0,
trace_id,
segment_id,
- -- Linked Lists
- finished_spans = nil,
+ is_noop = false,
+
+ internal,
}
-function TracingContext:new(o)
- o = o or {}
+function TracingContext:new()
+ local o = {}
setmetatable(o, self)
+ self.__index = self
- o.trace_id = idGen.newID();
+ o.trace_id = Util:newID();
o.segment_id = o.trace_id
+ o.internal = Internal:new()
+ o.internal.owner = o
return o
end
function TracingContext:createEntrySpan(operationName)
end
+-------------- Internal Object-------------
+-- Internal Object hosts the methods for SkyWalking LUA internal APIs only.
+Internal = {
+ -- span id starts from 0
+ span_id_seq,
+ -- Owner means the Context instance holding this Internal object.
+ owner,
+ -- Lists
+ -- Created span and still active
+ active_spans,
+ -- Finished spans
+ finished_spans,
+}
+
+-- Create an internal instance
+function Internal:new()
+ local o = {}
+ setmetatable(o, self)
+ self.__index = self
+
+ o.span_id_seq = 0
+ o.active_spans = {}
+ o.finished_spans = {}
+
+ return o
+end
+
+function Internal:addActive(span)
+ table.insert(self.active_spans, span)
+ return self.owner
+end
+
+-- Generate the next span ID.
+function Internal:nextSpanID()
+ local nextSpanId = self.span_id_seq
+ self.span_id_seq = self.span_id_seq + 1;
+ return nextSpanId
+end
+---------------------------------------------
+
return TracingContext
\ No newline at end of file
diff --git a/lib/skywalking/tracing_context_test.lua b/lib/skywalking/tracing_context_test.lua
index 9de8c7d..1b07dc1 100644
--- a/lib/skywalking/tracing_context_test.lua
+++ b/lib/skywalking/tracing_context_test.lua
@@ -16,18 +16,33 @@
--
local lu = require('luaunit')
-local tc = require('tracing_context')
+local TC = require('tracing_context')
TestTracingContext = {}
function TestTracingContext:testNew()
- local context = tc.new()
-
+ local context = TC:new()
+ lu.assertNotNil(context)
lu.assertNotNil(context.segment_id[1])
lu.assertNotNil(context.segment_id[2])
lu.assertNotNil(context.segment_id[3])
lu.assertEquals(context.trace_id, context.segment_id)
end
+
+ function TestTracingContext:testInternal_NextSpanSeqID()
+ local context = TC:new()
+
+ lu.assertEquals(context.internal:nextSpanID(), 0)
+ end
+
+ function TestTracingContext:testInternal_addActive()
+ local context = TC:new()
+
+ local mockSpan = {field = "ws"}
+ context.internal:addActive(mockSpan)
+
+ lu.assertEquals(#(context.internal.active_spans), 1)
+ end
-- end TestTracingContext
diff --git a/lib/skywalking/id_generator.lua b/lib/skywalking/util.lua
similarity index 60%
copy from lib/skywalking/id_generator.lua
copy to lib/skywalking/util.lua
index 3054774..ecabe7d 100644
--- a/lib/skywalking/id_generator.lua
+++ b/lib/skywalking/util.lua
@@ -15,16 +15,29 @@
-- limitations under the License.
--
-socket=require'socket'
-
-IDGenerator = {}
+Util = {}
MAX_ID_PART2 = 1000000000
MAX_ID_PART3 = 100000
SEQ = 1
-function IDGenerator:newID()
+function Util:newID()
SEQ = SEQ + 1
- return {socket.gettime(), math.random( 0, MAX_ID_PART2), math.random( 0, MAX_ID_PART3) + SEQ}
+ return {Util.timestamp(), math.random( 0, MAX_ID_PART2), math.random( 0, MAX_ID_PART3) + SEQ}
end
-return IDGenerator
\ No newline at end of file
+-- A simulation implementation of Java's System.currentTimeMillis() by following the SkyWalking protocol.
+-- Return the difference as string, measured in milliseconds, between the current time and midnight, January 1, 1970 UTC.
+-- But in using os.clock(), I am not sure whether it is accurate enough.
+function Util:timestamp()
+ local a,b = math.modf(os.clock())
+ if b==0 then
+ b='000'
+ else
+ b=tostring(b):sub(3,5)
+ end
+
+ return os.time() * 1000 + b
+end
+
+
+return Util
\ No newline at end of file
diff --git a/lib/skywalking/id_generator_test.lua b/lib/skywalking/util_test.lua
similarity index 80%
rename from lib/skywalking/id_generator_test.lua
rename to lib/skywalking/util_test.lua
index a536bed..e620017 100644
--- a/lib/skywalking/id_generator_test.lua
+++ b/lib/skywalking/util_test.lua
@@ -16,17 +16,22 @@
--
local lu = require('luaunit')
-local idGen = require('id_generator')
+local Util = require('util')
-TestIDGenerator = {}
- function TestIDGenerator:test()
- local id = idGen.newID()
+TestUtil = {}
+ function TestUtil:testNewID()
+ local id = Util.newID()
lu.assertNotNil(id[1])
lu.assertNotNil(id[2])
lu.assertNotNil(id[3])
end
--- end TestIDGenerator
+
+ function TestUtil:testTimestamp()
+ local id = Util.timestamp()
+ lu.assertNotNil(id)
+ end
+-- end TestUtil
os.exit( lu.LuaUnit.run() )
\ No newline at end of file
