为了支持Spark REPL功能,阿里云数据湖分析团队推出了本地安装Jupyter Lab和DLA Proxy、使用Docker快速启动环境两种方案,帮助用户将本地Jupyter Lab和阿里云DLA Spark连接在一起,从而可以利用DLA的弹性资源进行交互测试和计算。

注意事项

  • DLA Spark当前支持python3,Scala 2.11的Jupyter可交互作业。
  • 新版Jupyter Lab对Python的最低版本要求是Python 3.6。
  • 推荐使用Docker快速启动环境方式来使用本功能。
  • 交互式作业会在空闲一段时间后自动释放,默认释放时间为最后一个代码块执行完毕后1200秒。用户可以通过spark.dla.session.ttl来配置空闲多长时间后自动释放交互式作业。

本地安装Jupyter Lab和DLA Proxy

  1. 安装DLA Livy Proxy。
    1. 安装Aliyun OpenAPI SDK
      说明 Aliyun OpenAPI SDK的最低版本要求是2.0.4
    2. 使用以下命令安装Aliyun DLA Livy Proxy
      pip install aliyun-dla-livy-proxy-0.0.4.zip
      说明 您需要使用root用户安装Aliyun DLA Livy Proxy,非root用户进行安装可能无法注册命令到可执行目录中。Aliyun DLA Livy Proxy安装完成后,您可以在命令行中找到dlaproxy命令。
    3. 启动DLA Livy Proxy。
      DLA Livy Proxy用于将阿里云DLA的接口翻译为SparkMagic需要的Apache Livy语义接口,从而在本地建立HTTP PROXY监听与转发,端口默认是5000
      # 查看dlaproxy命令使用方式。
      $dlaproxy -h
      usage: dlaproxy [-h] --vcname VCNAME -i AK -k SECRET --region REGION [--host HOST] [--port PORT] [--loglevel LOGLEVEL]
      
      Proxy AliYun DLA as Livy
      
      optional arguments:
        -h, --help            show this help message and exit
        --vcname VCNAME       Virtual Cluster Name
        -i AK, --access-key-id AK
                              Aliyun Access Key Id
        -k SECRET, --access-key-secret SECRET
                              Aliyun Access Key Secret
        --region REGION       Aliyun Region Id
        --host HOST           Proxy Host Ip
        --port PORT           Proxy Host Port
        --loglevel LOGLEVEL   python standard log level
        
      # 直接启动dla livy proxy。
      dlaproxy --vcname <vcname> -i akid -k aksec --region <regionid>

      上述代码中出现的输入参数说明如下:

      参数名称 参数说明
      --vcname DLA Spark虚拟集群名称。
      说明 您可以登录Data Lake Analytics控制台,在虚拟集群管理 > 集群名称/实例ID > 详情中查看虚拟集群名称。
      -i RAM用户的AccessKey ID。
      说明 如果您已经创建了AccessKey,可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey,请参见为RAM用户创建访问密钥
      -k RAM用户的AccessKey Secret。
      说明 如果您已经创建了AccessKey,可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey,请参见为RAM用户创建访问密钥
      --region DLA所在地域对应的Region ID,详细信息请参见地域和可用区
      --host 服务绑定的Host,默认为127.0.0.1, 仅代理本地请求。可以修改为0.0.0.0或者其它地址监听公网/内网的请求并代理,建议使用默认值。
      --port 监听端口, 默认为5000, 可以修改为其它端口,建议使用默认值。
      --loglevel 日志级别, 默认为INFO,可以修改为ERROR、 WARNING、 INFO或DEBUG,建议使用默认值。
  2. 安装Jupyter Lab。
    1. 可选:安装venv
      说明 推荐将整套环境安装到Virtual Environment环境中,这样后续的安装不会破坏主账号下的公共Python环境。
    2. 使用以下命令安装Jupyter lab
      pip install jupyterlab #安装Jupyter Lab。
      jupyter lab  #验证一下是否安装成功, 成功安装的话, 可以看到启动日志。
    3. 按照如下步骤安装Sparkmagic。
      1. 安装库。
         pip install sparkmagic
      2. 确保ipywidgets成功运行。
         jupyter nbextension enable --py --sys-prefix widgetsnbextension
      3. 如果您使用的是JupyterLab,需要运行如下命令。
         jupyter labextension install "@jupyter-widgets/jupyterlab-manager"
      4. 使用pip show sparkmagic找到对应的文件夹,进入文件夹执行如下命令安装kernels。
         jupyter-kernelspec install sparkmagic/kernels/sparkkernel
         jupyter-kernelspec install sparkmagic/kernels/pysparkkernel
         jupyter-kernelspec install sparkmagic/kernels/sparkrkernel
      5. 修改~/.sparkmagic/config.json上的配置文件,详情请参见example_config.json
      6. 运行。
         jupyter serverextension enable --py sparkmagic
    安装成功后,需要手动创建配置文件~/.sparkmagic/config.json,并将url的配置指向本地开启的代理。示例如下:
    {
      "kernel_python_credentials" : {
        "username": "",
        "password": "",
        "url": "http://127.0.0.1:5000",
        "auth": "None"
      },
    
      "kernel_scala_credentials" : {
        "username": "",
        "password": "",
        "url": " http://127.0.0.1:5000",
        "auth": "None"
      },
      "kernel_r_credentials": {
        "username": "",
        "password": "",
        "url": "http://localhost:5000"
      },
    
      "logging_config": {
        "version": 1,
        "formatters": {
          "magicsFormatter": { 
            "format": "%(asctime)s\t%(levelname)s\t%(message)s",
            "datefmt": ""
          }
        },
        "handlers": {
          "magicsHandler": { 
            "class": "hdijupyterutils.filehandler.MagicsFileHandler",
            "formatter": "magicsFormatter",
            "home_path": "~/.sparkmagic"
          }
        },
        "loggers": {
          "magicsLogger": { 
            "handlers": ["magicsHandler"],
            "level": "DEBUG",
            "propagate": 0
          }
        }
      },
    
      "wait_for_idle_timeout_seconds": 15,
      "livy_session_startup_timeout_seconds": 600,
    
      "fatal_error_suggestion": "The code failed because of a fatal error:\n\t{}.\n\nSome things to try:\na) Make sure Spark has enough available resources for Jupyter to create a Spark context.\nb) Contact your Jupyter administrator to make sure the Spark magics library is configured correctly.\nc) Restart the kernel.",
    
      "ignore_ssl_errors": false,
    
      "session_configs": {
        "conf": {
          "spark.dla.connectors": "oss"
        }
      },
    
      "use_auto_viz": true,
      "coerce_dataframe": true,
      "max_results_sql": 2500,
      "pyspark_dataframe_encoding": "utf-8",
      
      "heartbeat_refresh_seconds": 30,
      "livy_server_heartbeat_timeout_seconds": 0,
      "heartbeat_retry_seconds": 10,
    
      "server_extension_default_kernel_name": "pysparkkernel",
      "custom_headers": {},
      
      "retry_policy": "configurable",
      "retry_seconds_to_sleep_list": [0.2, 0.5, 1, 3, 5],
      "configurable_retry_policy_max_retries": 8
    }
    说明 示例中的session_configs是提交到DLA Spark的conf部分,如果需要加载JAR包,连接DLA的元数据服务请参考作业配置指南
    DLA Livy Proxy启动后监听的默认地址为127.0.0.1:5000,如果在启动DLA Livy Proxy时修改了默认的Host和Port, 则需要修改上述配置文件中的url部分。示例:启动时指定地址 --host 192.168.1.3 --port 8080, 则应当将上述配置文件中的urlhttp://192.168.1.3:8080,修改后如下所示:
    { 
      "kernel_python_credentials" : {
        "username": "",
        "password": "",
        "url": "http://192.168.1.3:8080",
        "auth": "None"
      },
      "kernel_scala_credentials" : {
        "username": "",
        "password": "",
        "url": "http://192.168.1.3:8080",
        "auth": "None"
      },
      "kernel_r_credentials": {
        "username": "",
        "password": "",
        "url": "http://192.168.1.3:8080"
      },
     "logging_config": {
        "version": 1,
        "formatters": {
          "magicsFormatter": { 
            "format": "%(asctime)s\t%(levelname)s\t%(message)s",
            "datefmt": ""
          }
        },
        "handlers": {
          "magicsHandler": { 
            "class": "hdijupyterutils.filehandler.MagicsFileHandler",
            "formatter": "magicsFormatter",
            "home_path": "~/.sparkmagic"
          }
        },
        "loggers": {
          "magicsLogger": { 
            "handlers": ["magicsHandler"],
            "level": "DEBUG",
            "propagate": 0
          }
        }
      },
    
      "wait_for_idle_timeout_seconds": 15,
      "livy_session_startup_timeout_seconds": 600,
    
      "fatal_error_suggestion": "The code failed because of a fatal error:\n\t{}.\n\nSome things to try:\na) Make sure Spark has enough available resources for Jupyter to create a Spark context.\nb) Contact your Jupyter administrator to make sure the Spark magics library is configured correctly.\nc) Restart the kernel.",
    
      "ignore_ssl_errors": false,
    
      "session_configs": {
        "conf": {
          "spark.dla.connectors": "oss"
        }
      },
    
      "use_auto_viz": true,
      "coerce_dataframe": true,
      "max_results_sql": 2500,
      "pyspark_dataframe_encoding": "utf-8",
      
      "heartbeat_refresh_seconds": 30,
      "livy_server_heartbeat_timeout_seconds": 0,
      "heartbeat_retry_seconds": 10,
    
      "server_extension_default_kernel_name": "pysparkkernel",
      "custom_headers": {},
      
      "retry_policy": "configurable",
      "retry_seconds_to_sleep_list": [0.2, 0.5, 1, 3, 5],
      "configurable_retry_policy_max_retries": 8
    }
  3. 运行Jupyter Lab。
    # 重新启动Jupyter Lab。
    jupyter lab
    
    # 启动DLA Livy Proxy。
    dlaproxy --vcname vcname -i akid -k aksec --region <regionid>
    Jupyter Lab启动日志中会打印Jupyter Lab的本地地址。如下图所示:日志打印
    当系统出现提示Aliyun DLA Proxy is ready,表明DLA Livy Proxy启动成功。DLA Livy Proxy启动成功后,您就可以正常使用Jupyter Lab了。Jupyter Lab的使用文档,请参考jupyterlab官方地址
    运行Jupyter Lab任务,DLA中会自动创建DLA Spark作业,您可以登录Data Lake Analytics控制台,在Serverless Spark > 作业管理菜单进行查看和管理。如下图所示,名称以notebook_为开头的Spark作业即为Jupyter交互式作业。作业管理
    当Jupyter Lab运行起来后,您仍然可以动态的修改配置,修改方式是在Jupyter Lab代码单元中使用magic语句来覆盖旧的配置项。执行后,Jupyter Lab会根据新的配置项重启作业。
    # 重新启动Jupyter Lab。
    jupyter lab
    # 启动DLA Livy Proxy。
    dlaproxy --vcname vcname -i akid -k aksec --region <regionid>
    %%configure -f
    { 
        "conf": {
          "spark.sql.hive.metastore.version": "dla",
          "spark.dla.connectors": "oss"
        }
    }
    如果需要使用自制的依赖方法,您可以参考下述配置。
    %%configure -f
    { 
        "conf": {
          ...
        },
        "pyFiles": "oss://{your bucket name}/{path}/*.zip" # module
    }
  4. 关闭Jupyter Lab作业。

    单击JupyterLab Kernel菜单栏下的Restart Kernel

使用Docker快速启动环境

阿里云数据湖团队同时提供Docker镜像快速启动一个Jupyter交互式开发环境,Docker的安装和使用说明请参见Docker官方文档

  1. 安装并启动Docker后,使用如下命令拉取DLA Jupyter镜像。
    docker pull registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.4
  2. 拉取成功后,您可以使用如下命令查看此镜像的帮助文件。
    docker run -ti registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.2
    
    Used to run jupyter lab for Aliyun DLA 
    Usage example: docker run -it -p 8888:8888 dla-jupyter:0.1 -i akid -k aksec -r cn-hanghzou -c spark-vc -l INFO 
        -i Aliyun AkId
        -k Aliyun AkSec
        -r Aliyun Region Id
        -c Aliyun DLA Virtual cluster name
        -l LogLevel
    上述代码中出现的参数和DLA Proxy的参数非常相似,具体说明如下。
    参数名称 参数说明
    -c DLA Spark虚拟集群名称。
    说明 您可以登录Data Lake Analytics控制台。在虚拟集群管理 > 集群名称/实例ID > 详情中查看虚拟集群名称。
    -i RAM用户的AccessKey ID。
    说明 如果您已经创建了AccessKey,可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey,请参见为RAM用户创建访问密钥
    -k RAM用户的AccessKey Secret。
    说明 如果您已经创建了AccessKey,可以在RAM控制台上查看相关信息。关于如何查看以及创建AccessKey,请参见为RAM用户创建访问密钥
    -r DLA所在地域对应的Region ID,详细信息请参见地域和可用区
    -l 日志级别,默认为INFO,可以修改为ERROR、 WARNING、 INFO或DEBUG,建议使用默认值。
  3. 输入正确的参数,在本地启动对应的实例。
     docker run -it -p 8888:8888 registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.2 -i {AkId} -k {AkSec} -r {RegionId} -c {VcName}                           
    启动成功后您可以看到如下图所示的提示信息,将标注框中的网址贴入浏览器可开始使用Jupyter服务直连DLA Spark。启动成功
注意事项
  • 在排查错误时需要观察底层日志,文件浏览框中的dlaproxy.log即为日志记录文件,正确的启动信息如下图所示。启动信息
  • 在不挂载宿主机文件夹的情况下,关闭Docker后编辑的文件会丢失。Docker关闭时也会自动尝试终止所有正在运行的Spark交互式作业。此时,您可以选择如下两种方案。
    • 在关闭Docker前保证所有的文件被妥善的复制保管。
    • 将本地文件夹挂载到Docker镜像中,并将作业文件存储在对应的文件夹下。

      以Linux环境为例,将文件夹/home/admin/notebook挂载到Docker实例/root/notebook文件夹下,启动命令如下。

       docker run -it --privileged=true -p 8888:8888  -v /home/admin/notebook:/root/notebook registry.cn-hangzhou.aliyuncs.com/dla_spark/dla-jupyter:0.2 -i {AkId} -k {AkSec} -r {RegionId} -c {VcName}                           

      需要注意将编辑中的notebook最终另存到/tmp,关闭Docker示例后,在宿主机的/home/admin/notebook文件夹下可以看到对应的文件,下次启动Docker实例时可以接着工作。

      说明 更多信息,请参见 Docker卷管理文档

常见问题处理

  • 问题现象:Jupyter Lab启动失败,出现如下报错,如何处理?
    • [C 09:53:15.840 LabApp] Bad config encountered during initialization:
    • [C 09:53:15.840 LabApp] Could not decode '\xe6\x9c\xaa\xe5\x91\xbd\xe5\x90\x8d' for unicode trait 'untitled_notebook' of a LargeFileManager instance.

    解决方法:LANG=zn jupyter lab。

  • 问题现象:出现报错$ jupyter nbextension enable --py --sys-prefix widgetsnbextension Enabling notebook extension jupyter-js-widgets/extension... - Validating: problems found: - require? X jupyter-js-widgets/extension,如何处理?

    解决方法:jupyter nbextension install --py widgetsnbextension --userjupyter nbextension enable widgetsnbextension --user --py

  • 问题现象:出现报错ValueError: Please install nodejs >=12.0.0 before continuing. nodejs may be installed using conda or directly from the nodejs website.,如何处理?

    解决方法:conda install nodejs。关于安装Conda请参考Conda官方文档

  • 问题现象:安装Sparkmagic时报错失败,如下图所示,如何处理?报错截图

    解决方法:安装Rust。

  • 问题现象: 无法使用matplot进行绘图, 即使加入了%matplotlib inline仍然会报错如下图所示。

    matplot报错示意图

    解决方法: 当使用云端PySpark时, 使用%matplot plt组合plt.show()绘制图表, 效果如下图所示。

    matplot正确用法