{"id":13452756,"url":"https://github.com/luin/ranaly","last_synced_at":"2025-04-05T15:08:48.940Z","repository":{"id":6901780,"uuid":"8151767","full_name":"luin/ranaly","owner":"luin","description":"📈 An easy to use chart system","archived":false,"fork":false,"pushed_at":"2020-08-09T08:11:10.000Z","size":2599,"stargazers_count":497,"open_issues_count":5,"forks_count":78,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-03-29T14:11:22.319Z","etag":null,"topics":["analytics","nodejs","pie-chart","realtime"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"ajaxorg/cloud9","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-12T02:53:09.000Z","updated_at":"2024-10-28T01:47:28.000Z","dependencies_parsed_at":"2022-07-10T17:30:44.045Z","dependency_job_id":null,"html_url":"https://github.com/luin/ranaly","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luin%2Franaly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luin%2Franaly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luin%2Franaly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luin%2Franaly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luin","download_url":"https://codeload.github.com/luin/ranaly/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353746,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","nodejs","pie-chart","realtime"],"created_at":"2024-07-31T08:00:22.266Z","updated_at":"2025-04-05T15:08:48.914Z","avatar_url":"https://github.com/luin.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Ranaly\nRanaly是一个基于Redis的数据统计可视化工具。\n\nRanaly的Node.js客户端库[node_ranaly](https://github.com/luin/node_ranaly)已经完成。\n\n![效果图](./assets/preview.png)\n\n特点如下：\n\n1. 使用简单，容易维护\n2. 基于Redis，性能优异\n3. 支持模块级别的权限控制\n4. 长连接实时数据统计\n5. 多种图表可以选择，可以自定义模板、模块\n\n## 快速入门\n在项目中使用Ranaly统计数据十分简单，步骤如下。\n### 1. 安装Node.js和Redis\nRanaly使用Node.js开发，所以需要先安装[Node.js](http://nodejs.org/)。同样因为Ranaly的统计数据存储于Redis中，所以需要安装[Redis](http://redis.io/)。\n### 2. 安装Ranaly\n\n\tgit clone git://github.com/luin/ranaly.git\n\tcd ranaly\n\tnpm install\n\n### 3. 在已有项目中加入统计代码\n如果你的项目使用Node.js开发，可以使用Ranaly的node客户端库，安装方法如下：\n\n\tnpm install node_ranaly\n\n如果希望统计项目注册用户的变化趋势，可以在用户注册成功后加上如下代码：\n\n\tvar ranaly = require('node_ranaly').createClient();\n\tvar rUsers = new ranaly.Amount('Users');\n\trUsers.incr();\n\nnode_ranaly库会将名为“Users”的Amount类型的桶的值增1并和当前时间一起写入到Redis中。\n\n### 4. 查看统计结果\n建立配置文件，内容如下：\n\n\tapp_name: Demo\n\tusers:\n\t  - username: admin\n\t    password: admin123\n\tpages:\n\t  - title: Overview\n\t    widgets:\n\t      - type: amount_line_chart\n\t        bucket: Users\n\n将文件保存，并进入Ranaly的目录执行：\n\n\tnode ranaly /path/to/config_file\n\n其中`/path/to/config_file`表示配置文件路径。此时就可以访问 http://127.0.0.1:3000 进入数据查看页面了，使用admin和admin123登录系统，能看到用户数量的折线图。\n\n## 文档\nRanaly由两个部分组成，分别是客户端库和数据展示部分，本页面项目是数据展示部分。在程序中通过客户端库在Redis中记录统计数据，而本页面项目的作用是将这些数据以图表的形式显示出来。\n\n### 1. 客户端库\nNode.js：[node_ranaly](https://github.com/luin/node_ranaly)\n\n### 2. 数据类型\n为了适应不同场合的统计需要，Ranaly支持3种类型的数据统计：\n\n#### (1) Amount\n当要记录某一个数据的在不用时间的数量变化时就需要使用Amount类型，如想记录用户数量的变化趋势等。\n\n#### (2) Realtime\nRealtime用来记录实时数据，如当前系统内存使用情况等。\n\n#### (3) DataList\nDataList用来记录数据列表，数据可以是数字、字符串甚至对象。如新注册的用户头像地址列表、新注册的用户资料列表等。DataList只保留数据列表中的前N条数据（N的数值可以指定）。\n\n### 3. Ranaly配置文件\n为了能够通过Ranaly来将Redis中记录的统计数据可视化，需要提供一份配置文件。配置文件的格式为YAML，样例如下：\n\n\tapp_name: 应用名称\n\tport: Ranaly使用的端口号，默认是3000\n\tredis:\n\t\thost: Redis的主机地址，默认是127.0.0.1\n\t\tport: Redis的端口号，默认是6379\n\t\tkey_prefix: 存储统计数据的键名前缀，需要和客户端库的配置一样\n\tusers:\n\t\t- username: 用户名\n\t\t  password: 密码\n\t\t  role: 数字，表示用户的权限，默认是0\n\tpages:\n\t\t- title: 页面的标题\n\t\t  widgets:\n\t\t  \t  - type: widget的类型\n\t\t  \t    bucket: widget对应的bucket\n\t\t  \t    title: widget的标题\n\t\t\t    role: 数字，只对拥有大于或等于该role的用户可见\n\n### 4. 桶（bucket）\n为了区分不同的统计数据，需要为每类数据起个名字（桶），如统计用户名称的桶可以命名为“Users”，统计访问量的桶可以命名为“Page views”。不同数据类型的桶可以重名，桶的名称可以包含空格。\n\n### 5. Widget类型\n在配置文件中可以看到每一个项目是由若干个page组成的，每个page由若干个widget组成。widget分为不同种类，每一种widget只适用于一种数据类型，可以从其命名看出来。\n\n#### (1) amount_line_chart\n该类型的widget用来显示折线图，只支持Amount。每个widget除了type、bucket、title和role四个参数外还支持其它不同的参数。amount_line_chart类型支持的参数如下：\n\n|      参数名      |    意义     |                               取值                                |\n|---------------|-----------|-----------------------------------------------------------------|\n| default_range | 默认显示的时间范围 | today（显示当天的数据），yesterday（昨天的数据），7days（最近7天的数据），30days（最近30天的数据） |\n| update_interval | 数据更新间隔，默认为20-40秒 | 数字，单位为秒                                                                   |\n\n\n![doc_amount_line_chart](./assets/doc_amount_line_chart.png)\n\namount_line_chart支持同时显示多个bucket的数据，在配置文件中以数组形式设置，如：\n\n\ttype: amount_line_chart\n\tbucket: [Users, Page views, Groups]\n\n#### (2) amount_pie_chart\n用来显示饼图。amount_pie_chart类型支持的其它参数如下：\n\n|      参数名      |    意义     |                                    取值                                     |\n|---------------|-----------|---------------------------------------------------------------------------|\n| default_range | 默认显示的时间范围 | today（显示当天的数据），yesterday（昨天的数据），7days（最近7天的数据），30days（最近30天的数据），all（所有数据） |\n| update_interval | 数据更新间隔，默认为20-40秒 | 数字，单位为秒                                                                   |\n\n\namount_pie_chart支持同时比对多个bucket的数据。\n\n![doc_amount_pie_chart](./assets/doc_amount_pie_chart.png)\n\n#### (3) amount_today_count\n用来显示当天的数据，并根据昨天同时间的数据预测今天的全天的数据。支持的其它参数如下：\n\n|      参数名      |    意义     |                                    取值                                     |\n|---------------|-----------|---------------------------------------------------------------------------|\n| update_interval | 数据更新间隔，默认为20-40秒 | 数字，单位为秒                                                                   |\n\n\n![doc_amount_today_count](./assets/doc_amount_today_count.png)\n\namount_today_count支持同时显示多个bucket的数据。\n\n#### (4) amount_total_count\n显示某一时间范围的数据总和，如最近30天注册的用户总数。支持的其它参数如下：\n\n|      参数名      |    意义     |                                    取值                                     |\n|---------------|-----------|---------------------------------------------------------------------------|\n| update_interval | 数据更新间隔，默认为20-40秒 | 数字，单位为秒                                                                   |\n\n\n![doc_amount_total_count](./assets/doc_amount_total_count.png)\n\namount_total_count支持同时显示多个bucket的数据。\n\n#### (5) realtime_line_chart\n显示实时数据的折线图，更新频率是1秒。\n\n![doc_realtime_line_chart](./assets/doc_realtime_line_chart.png)\n\nrealtime_line_chart支持同时显示多个bucket的数据。\n\n#### (6) realtime_count\n显示实时数据的数值，更新频率是实时。\n\n![doc_realtime_count](./assets/doc_realtime_count.png)\n\nrealtime_count支持同时显示多个bucket的数据。\n\n#### (7) datalist_list\n显示DataList数据列表。由于DataList类型可以存储任何数据的列表，所以该类型的widget支持高度自定义。可以通过template参数指定显示DataList的模板，模板采用[Mustache](http://mustache.github.com/)，渲染的数据格式是{\"data\": [*数据列表*]}。下面的实例中还会对此进行介绍。除此之外还支持count_per_page参数用来指定每页要显示的数据条数。\n\n![doc_datalist_list](./assets/doc_datalist_list.png)\n\n#### (8) custom_code\n该widget类型比较特殊，无需bucket参数，只需要content参数。作用是执行自定义的代码，包括HTML/CSS/JavaScript。如：\n\n      - type: custom_code\n        content: \u003e\n          \u003cp\u003ehi\u003c/p\u003e\n\n## 综合实例\n现在假设要统计Facebook网站的数据，以使用Ranaly的Node.js客户端为例。首先我们通过node_ranaly建立到Redis的连接（假设Redis运行在本机6380端口上）：\n\n\tvar ranaly = require('node_ranaly');\n\tvar ranalyClient = ranaly.createClient(6380, '127.0.0.1');\n\n首先要统计的是用户的数量，每当用户注册成功都调用如下代码令Users桶的数值加1：\n\n\tvar rUsers = new ranalyClient.Amount('Users');\n\trUsers.incr();\n\n然后我们要统计网站的访问量，每当访问一个页面时，都执行：\n\n\tvar rPageViews = new ranalyClient.Amount('Page views');\n\trPageViews.incr();\n\n现在来配置Ranaly可视化部分来显示我们的统计数据：\n\n\tapp_name: Facebook\n\tredis:\n\t\thost: 127.0.0.1\n\t\tport: 6380\n\tusers:\n\t\t- username: admin\n\t\t  password: admin123\n\tpages:\n\t\t- title: Overview\n\t\t  widgets:\n\t\t    - type: amount_line_chart\n\t\t      bucket: [Users, Page views]\n\n在这个配置中，我们使用折线图来比对用户数量和访问量的关系。将该内容存为config.yaml，然后执行：\n\n\t$ node ./ranaly.js /path/to/config.yaml\n\tRanaly server listening on port 3000\n\n此时就可以通过http://127.0.0.1:3000来访问了。\n\n在Facebook中，用户可以发布文字状态、照片和视频，若想统计这3种类型的状态的比例，可以在发布时执行：\n\n\tvar bucket = '';\n\tswitch (status.type) {\n\tcase 'text':\n\t\tbucket = 'Text';\n\t\tbreak;\n\tcase 'photo':\n\t\tbucket = 'Photo';\n\t\tbreak;\n\tcase 'video':\n\t\tbucket = 'Video';\n\t\tbreak;\n\t}\n\tvar rStatus = new ranalyClient.Amount(bucket);\n\trStatus.incr();\n\n然后我们接着编辑config.yaml，在widgets中加入：\n\n\t\t\t    - type: amount_pie_chart\n\t\t\t      bucket: [Text, Photo, Video]\n\n这时重新启动Ranaly服务器（每次修改config.yaml都得重启），可以看到显示3者比例的饼图，并且可以随意调整时间范围。\n\n接下来显示服务器的资源，包括内存和CPU：\n\n\tvar rMemory = new ranalyClient.Realtime('Memory');\n\tvar rCPU = new ranalyClient.Realtime('CPU');\n\tsetInterval(function () {\n\t\trMemory.set(System.getUsedMemory());\n\t\trCPU.set(System.getUsedCPU());\n\t}, 100);\n\n嗯...好像是没有System.getUsedMemory()和System.getUsedCPU()这两个东西，不过只要知道他们都会返回个数字就好了。\n\n同样我们接着编辑config.yaml，在widgets中加入：\n\n\t\t\t    - type: realtime_count\n\t\t\t      bucket: [Memory, CPU]\n\n重启服务器，就可以看到空闲的内存和CPU资源了。每次Realtime类型的数据更新都会推送给Ranaly服务器，所以页面上显示的数值每100毫秒变一次。\n\n现在我们还希望能在Ranaly页面中看到用户最新上传的头像，所以我们在头像上传成功后执行：\n\n\tvar rAvatar = new ranalyClient.DataList('Avatar');\n\trAvatar.push(avatarURL, 100);\n\n其中`avatarURL`是一个字符串，存储用户头像的URL地址。100表示只存储最新的100条记录，防止数据占用过多的内存（因为数据是存储在Redis中的）。\n\n接着我们来配置config.yaml：\n\n\t\t\t    - type: datalist_list\n\t\t\t      bucket: [Avatar]\n\n默认会以列表的形式展示数据，不是很好看，所以我们来自定义模板。Ranaly使用了BootStrap框架，所以可以在模板中自由使用BootStrap的风格。我们将数据修改成：\n\n\t\t\t    - type: datalist_list\n\t\t\t      bucket: [Avatar]\n\t\t\t      template: \u003e\n\t\t\t\t\t\t\u003cul class=\"thumbnails\" style=\"margin-right: -20px\"\u003e\n\t\t\t\t\t\t  {{#data}}\n\t\t\t\t\t\t  \u003cli class=\"span2\" style=\"width: 135px\"\u003e\n\t\t\t\t\t\t    \u003ca href=\"{{.}}\" class=\"thumbnail\"\u003e\n\t\t\t\t\t\t      \u003cimg src=\"{{.}}\" alt=\"\" width=\"150\" height=\"150\" /\u003e\n\t\t\t\t\t\t    \u003c/a\u003e\n\t\t\t\t\t\t  \u003c/li\u003e\n\t\t\t\t\t\t  {{/data}}\n\t\t\t\t\t\t\u003c/ul\u003e\n\n对于展示图片，Ranaly提供了一个预置的模板，可以这样写：\n\n\t\t\t    - type: datalist_list\n\t\t\t      bucket: [Avatar]\n\t\t\t      preset_template: images\n\n接着我们想记录最近注册成功的用户的资料，则在用户注册成功后执行：\n\n\tvar rUsers = new ranalyClient.DataList('Users');\n\trUsers.push({\n\t\tid: user.id,\n\t\tname: user.name,\n\t\tage: user.age,\n\t\tdescription: user.description\n\t}, 100);\n\n然后修改配置文件：\n\n\t\t\t    - type: datalist_list\n\t\t\t      bucket: [Users]\n\t\t\t      template:\n\t\t\t          \u003ctable class=\"table table-hover table-bordered\"\u003e\n\t\t\t            \u003cthead\u003e\n\t\t\t              \u003ctr\u003e\n\t\t\t                \u003cth\u003eID\u003c/th\u003e\n\t\t\t                \u003cth\u003ename\u003c/th\u003e\n\t\t\t                \u003cth\u003eage\u003c/th\u003e\n\t\t\t                \u003cth\u003edescription\u003c/th\u003e\n\t\t\t              \u003c/tr\u003e\n\t\t\t            \u003c/thead\u003e\n\t\t\t            \u003ctbody\u003e\n\t\t\t              {{#data}}\n\t\t\t              \u003ctr\u003e\n\t\t\t                \u003ctd\u003e{{id}}\u003c/td\u003e\n\t\t\t                \u003ctd\u003e{{name}}\u003c/td\u003e\n\t\t\t                \u003ctd\u003e{{age}}\u003c/td\u003e\n\t\t\t                \u003ctd\u003e{{description}}\u003c/td\u003e\n\t\t\t              \u003c/tr\u003e\n\t\t\t              {{/data}}\n\t\t\t            \u003c/tbody\u003e\n\t\t\t          \u003c/table\u003e\n\n就可以看到记录最新注册用户资料的表格了。\n\n\n[![Bitdeli Badge](https://d2weczhvl823v0.cloudfront.net/luin/ranaly/trend.png)](https://bitdeli.com/free \"Bitdeli Badge\")\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluin%2Franaly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluin%2Franaly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluin%2Franaly/lists"}